Aller au contenu

Galaxie Artibox

Authentification de l'API, de jetons personnels à OAuth 2 avec PKCE

Un jeton personnel pour vos propres outils, une application OAuth pour agir au nom d'autres comptes. Les deux s'envoient dans l'en-tête x-api-key.

L'API accepte deux sortes de jetons, toujours dans l'en-tête x-api-key : le jeton personnel, pour vos propres scripts et outils, et le jeton d'accès OAuth, obtenu par OAuth 2 avec PKCE quand votre application agit au nom d'autres personnes. L'en-tête Authorization n'est pas lu.

Les jetons personnels

Un membre crée ses jetons dans Réglages › Intégrations, carte « API » (formule Pro ou plus) : un nom, une date d'expiration facultative et des portées. Le jeton commence par rdv_pat_ et n'est affiché qu'une fois ; seule son empreinte est conservée. Il agit au nom de son membre, dans son organisation, avec les droits de son rôle et les seules portées cochées. Un jeton ne peut jamais créer un autre jeton : la gestion des jetons reste dans l'application.

curl "$RDV_API/users/me" -H "x-api-key: rdv_pat_…"

La procédure dans l'application est décrite dans l'aide API et jetons.

Les portées

Chaque route demande une portée ; la référence la donne pour chacune. Hors portée, la réponse est 403 et nomme la portée manquante.

  • utilisateur:lire : le compte du jeton, son contexte et ses notifications.
  • organisation:lire, organisation:administrer : l'organisation, ses réglages, ses membres, ses invitations.
  • types:lire, types:ecrire : les types de rendez-vous, leurs créneaux, leurs messages, les réunions ponctuelles.
  • disponibilites:lire, disponibilites:ecrire : les plannings, les exceptions, les heures occupées.
  • reservations:lire, reservations:ecrire : les rendez-vous et les sondages.
  • liens:ecrire : les liens uniques, les liens signés et les envois de lien.
  • webhooks:ecrire : les abonnements aux webhooks et leurs livraisons.
  • journal:lire : le journal d'audit de l'organisation.
  • donnees:effacer : l'export et l'effacement des données d'un invité.

Demandez toujours les portées les plus étroites : un outil qui affiche des créneaux n'a besoin que de types:lire.

OAuth 2 avec PKCE, pas à pas

OAuth sert quand votre application agit au nom de comptes qui ne sont pas le vôtre, par exemple les utilisateurs de votre logiciel. Le parcours est celui du code d'autorisation, avec PKCE (S256) obligatoire et un state.

1. Déclarer l'application

Dans votre organisation, le propriétaire ouvre Réglages › Intégrations › Applications OAuth et déclare l'application : nom, adresses de retour (redirect_uri) et portées autorisées. Il reçoit le client_id (rdv_app_…) et le secret (rdv_cs_…, affiché une seule fois). Les membres de n'importe quelle organisation peuvent ensuite l'autoriser : voir intégrer dans votre plateforme.

2. Préparer le code PKCE

CODE_VERIFIER=$(openssl rand -hex 32)
CODE_CHALLENGE=$(printf '%s' "$CODE_VERIFIER" | openssl dgst -sha256 -binary | openssl base64 | tr '+/' '-_' | tr -d '=\n')
STATE=$(openssl rand -hex 16)

Gardez CODE_VERIFIER et STATE côté serveur, liés à la session de l'utilisateur.

3. Envoyer l'utilisateur sur l'écran de consentement

https://adresse-de-votre-application/oauth/autoriser
  ?response_type=code
  &client_id=rdv_app_…
  &redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fretour
  &scope=types%3Alire%20reservations%3Alire
  &state=STATE
  &code_challenge=CODE_CHALLENGE
  &code_challenge_method=S256

L'utilisateur se connecte s'il le faut, lit ce que demande l'application et accepte. Il revient sur votre redirect_uri avec ?code=rdv_code_…&state=…, ou ?error=access_denied&state=… s'il refuse. Vérifiez que state est bien le vôtre.

4. Échanger le code contre des jetons

Le code vaut 10 minutes et ne sert qu'une fois. Votre serveur l'échange, avec le secret dans le corps (client_secret_post, en formulaire ou en JSON) :

curl -X POST "https://adresse-de-votre-application/api/webhooks/oauth/token" \
  -d grant_type=authorization_code \
  -d code=rdv_code_… \
  -d redirect_uri=https://example.com/oauth/retour \
  -d code_verifier="$CODE_VERIFIER" \
  -d client_id=rdv_app_… \
  -d client_secret=rdv_cs_…
{ "access_token": "rdv_oat_…", "token_type": "Bearer", "expires_in": 7200, "refresh_token": "rdv_ort_…", "scope": "types:lire reservations:lire" }

Malgré token_type, le jeton d'accès s'envoie dans x-api-key, comme un jeton personnel. Un code présenté une seconde fois arrête tous les jetons qu'il a donnés.

5. Appeler l'API

curl "$RDV_API/users/me" -H "x-api-key: rdv_oat_…"

Rafraîchir, révoquer, inspecter

Rafraîchir

Le jeton d'accès vit 2 heures, le jeton de rafraîchissement 90 jours. Chaque rafraîchissement rend une nouvelle paire et retire l'ancienne : gardez toujours le dernier jeton de rafraîchissement. Réutiliser un ancien jeton de rafraîchissement coupe tout l'accès de l'application pour ce membre.

curl -X POST "https://adresse-de-votre-application/api/webhooks/oauth/token" \
  -d grant_type=refresh_token -d refresh_token=rdv_ort_… \
  -d client_id=rdv_app_… -d client_secret=rdv_cs_…

Révoquer

curl -X POST "https://adresse-de-votre-application/api/webhooks/oauth/revoke" \
  -d token=rdv_ort_… -d client_id=rdv_app_… -d client_secret=rdv_cs_…

L'utilisateur peut aussi retirer l'accès lui-même, dans « Applications connectées ».

Inspecter un jeton (introspection)

curl -X POST "https://adresse-de-votre-application/api/webhooks/oauth/introspect" \
  -d token=rdv_oat_… -d client_id=rdv_app_… -d client_secret=rdv_cs_…

La réponse suit la RFC 7662 : {"active": true, "scope": …, "client_id": …, "exp": …, "sub": …, "username": …, "organization_id": …}, ou {"active": false} pour un jeton inconnu, expiré, retiré ou d'une autre application.

Les métadonnées du serveur

Le document RFC 8414 est servi à https://adresse-de-votre-application/.well-known/oauth-authorization-server : adresses d'autorisation, de jeton, de révocation, d'introspection, portées et méthodes acceptées. La route GET /users/me sert de point « userinfo ».

Les erreurs d'authentification

  • Les appels de /api/webhooks/oauth/… répondent 404 tant que client_id et client_secret ne sont pas bons : c'est volontaire.
  • Ensuite, les erreurs suivent OAuth 2 : 400 avec {"error": "invalid_grant"} (code expiré, déjà servi, mauvais code_verifier ou redirect_uri), unsupported_grant_type…
  • Sur l'API, un jeton absent ou refusé répond 401, une portée manquante 403. Voir limites et erreurs.

Questions fréquentes

Jeton personnel ou OAuth, lequel choisir ?

Le jeton personnel pour vos propres outils, au nom d'un seul membre. OAuth dès que votre application sert d'autres personnes : chacune l'autorise et peut retirer l'accès.

Le PKCE est-il obligatoire ?

Oui, avec la méthode S256 seulement. Un code d'autorisation sans code_challenge est refusé.

Puis-je envoyer le jeton dans l'en-tête Authorization ?

Non : l'API lit uniquement x-api-key. Le jeton d'accès OAuth s'y envoie comme un jeton personnel.

Que se passe-t-il si le compte du membre est désactivé ?

Ses jetons et les accès qu'il a donnés cessent de fonctionner : un jeton n'agit jamais au-delà de son membre.

Déclarez votre application OAuth

Créez votre compte, passez en formule Pro et déclarez votre application dans Réglages › Intégrations.

Créer mon compte