Aller au contenu

API

L’API JamCloud permet à un script, un tableur ou une autre application de lire et de modifier vos espaces : lister les morceaux, importer des fichiers, récupérer sections et grilles. Elle voit exactement ce que vous voyez, dans chaque espace dont vous êtes membre.

Une clé personnelle (elle commence par jc_) vous représente auprès de l’API. Tous les comptes n’incluent pas les clés ; un administrateur peut vous accorder l’accès. Sans lui, Réglages › Clés API indique que votre compte n’inclut pas l’accès à l’API.

Dans Réglages › Clés API, donnez un nom à la clé, puis choisissez :

  • Lecture seule : la clé lit, sans jamais rien modifier.
  • Lecture et écriture : la clé peut aussi importer, modifier et supprimer, dans la limite de votre rôle dans chaque espace.
  • Son expiration : jamais, ou dans 30, 90 ou 365 jours.

La clé n’est affichée qu’une fois, juste après Créer la clé : copiez-la et gardez-la en lieu sûr, comme un mot de passe. La liste n’en montre ensuite que le début, sa dernière utilisation et son expiration. Révoquer arrête une clé aussitôt. Vous pouvez avoir 10 clés actives.

Envoyez la clé dans l’en-tête Authorization :

curl -H "Authorization: Bearer jc_…" https://api-jamcloud.australfactory.cl/api/v1/groups

Cet appel liste vos espaces. La plupart des autres routes se trouvent sous un espace (/api/v1/groups/<id>/…).

Une clé n’atteint jamais votre compte : connexion, profil, sécurité, notifications, autres clés API et administration (/auth, /me, /admin, /realtime, /api-keys) répondent 403 avec le code api_key_forbidden. Gérez-les dans l’application. Une clé en Lecture seule qui tente de modifier quelque chose reçoit 403 api_key_read_only.

Quand l’API est temporairement coupée, chaque appel avec une clé reçoit 503 circuit_open : attendez le nombre de secondes indiqué dans l’en-tête Retry-After, puis réessayez. L’application, elle, continue de fonctionner.

La référence de l’API (version 1) liste chaque route accessible avec une clé, avec ses paramètres, ses champs et un exemple prêt à lancer.