S’authentifier sur l’API

L’API publique n’accepte pas votre clé d’API directement : vous l’échangez contre un jeton d’accès, que vous présentez ensuite sur chaque appel. Il n’existe pas d’en-tête de clé statique. Cet article décrit cet échange, la durée de vie des jetons, l’identité qu’ils portent et les erreurs renvoyées.

⚠️ Prérequis : vous devez disposer d’une clé d’API. Elle se génère dans Configuration > Intégration > Developers API, une entrée qui n’apparaît que si l’option d’API publique est ouverte sur votre compte. La procédure est décrite dans Générer et gérer vos clés d’API.

Échanger la clé contre un jeton

Envoyez un POST sur /v1/token en plaçant la clé dans le corps de la requête, sous la forme { "appSecret": "votre_clé" }. Cet appel n’est pas authentifié : la clé est la seule preuve d’identité.

La réponse contient deux jetons, { "access_token": "…", "refresh_token": "…" }. Conservez-les tous les deux : le premier authentifie vos appels, le second sert à renouveler le premier.

Présenter le jeton sur vos appels

Sur tous les appels suivants, placez le jeton d’accès dans l’en-tête Authorization: Bearer <access_token>.

⚠️ Le préfixe Bearer est obligatoire, espace compris. Envoyer le jeton nu renvoie un 400, distinct de l’erreur d’un jeton invalide.

Renouveler le jeton d’accès

Le jeton d’accès est valable 6 heures et le jeton de rafraîchissement 730 heures, soit environ un mois. Ces durées sont fixées côté serveur et ne se paramètrent pas.

Pour renouveler, envoyez un POST sur /v1/token/refresh avec { "refreshToken": "…" }. La réponse renvoie un nouveau jeton d’accès et un nouveau jeton de rafraîchissement.

⚠️ Le jeton de rafraîchissement est à usage unique. Celui que vous venez d’employer est consommé : stockez le nouveau à sa place. Une intégration qui rejoue toujours le même jeton reçoit un 404 au deuxième essai.

⚠️ Un seul jeton de rafraîchissement reste valide à la fois par compte. Repasser par /v1/token consomme le précédent, quelle que soit la clé utilisée : deux intégrations qui partagent un compte se déconnectent donc mutuellement. Faites porter le renouvellement par un seul processus.

💡 Conseil : obtenir un jeton ne suffit pas à valider votre intégration. Laissez-la tourner plus de six heures et vérifiez qu’elle franchit le renouvellement sans intervention.

L’identité portée par le jeton

Le jeton identifie le compte, jamais une personne. Il n’agit au nom d’aucun administrateur ni d’aucun apprenant, et ce qu’il écrit n’est attribué à personne. Les lectures restent cloisonnées sur ce compte, qu’il s’agisse des utilisateurs, des groupes, des capsules, des parcours ou des catégories.

Les limites à connaître

• La portée est définie au niveau du compte. Toutes les clés d’un même compte reçoivent la même portée : vous ne pouvez pas créer une clé limitée à la lecture, à un groupe ou à un département.
• Un jeton déjà émis ne se révoque pas. Supprimer une clé n’annule pas le jeton d’accès qui en est issu : il reste valable jusqu’au bout de ses 6 heures.
• Il n’existe pas de quota d’appels. Aucune limitation de débit ne s’applique sur l’API publique, donc rien ne vous protège d’une boucle partie de votre côté.

L’URL de base

Tous les appels sont adressés à https://api.developers.beedeez.com. Les entrées /v1/token et /v1/token/refresh, avec leurs schémas, sont décrites dans la référence OpenAPI publiée sur doc.developers.beedeez.com .

Les réponses d’erreur

Situation	Code	Message
En-tête Authorization absent	401	No jwt token provided
Préfixe Bearer manquant	400	Invalid authorization prefix, should be `Bearer token_value`
Jeton expiré	401	jwt expired
Jeton tronqué ou signé ailleurs	401	jwt malformed, invalid signature
Clé inconnue ou supprimée, sur /v1/token	404	Credentials not found
Jeton de rafraîchissement déjà consommé	404	Refresh Token not found

Le corps de la réponse porte toujours les champs message, kind et statusCode.

💡 Conseil : distinguez le 401 du 404 dans votre traitement d’erreur. Un 401 se règle en renouvelant le jeton, alors qu’un 404 sur /v1/token signifie que la clé n’existe plus : réessayer ne la fera pas revenir.

Pour aller plus loin

• Générer et gérer vos clés d’API : où la clé se crée, et pourquoi elle ne s’affiche qu’une seule fois.
• Les ressources disponibles : la référence des points d’entrée, tenue à jour en dehors de cette base.
• API publique, webhooks, callbacks : que choisir : vérifier qu’un développement est nécessaire avant de l’engager.
• Faire remonter une complétion depuis un outil tiers : le seul appel qui s’authentifie autrement, par un jeton porté dans l’URL.