Construire sur le réseau

1. 1

   Créez une clé dans les paramètres développeur. Donnez-lui un nom, uniquement les portées dont elle a besoin, et une date d’expiration si elle sert à quelque chose de temporaire.

   Tant que votre adresse e-mail n’est pas confirmée, une clé ne peut porter que les portées de lecture.

2. 2

   Copiez la clé quand elle s’affiche. Elle n’apparaît qu’une fois : seule une empreinte en est conservée, une clé perdue ne se récupère donc pas, elle se remplace.

3. 3

   Envoyez-la comme jeton bearer à chaque requête :

   shell

   curl https://api.thecubefloor.com/v1/me \
     -H "Authorization: Bearer dk_…"

   Copier
4. 4

   Révoquez-la depuis la même page dès qu’elle ne sert plus. La liste indique quand chaque clé a servi pour la dernière fois.

Le flux par code d’autorisation, avec PKCE (S256) obligatoire à chaque requête. Chaque application est un client confidentiel doté d’un secret.

1. 1

   Enregistrez l’application dans les paramètres développeur : son nom (les gens le voient quand on leur demande leur accord), ses URI de redirection et les portées qu’elle peut demander. Vous obtenez un client_id et un client_secret, le secret affiché une seule fois. Enregistrer une application demande une adresse e-mail confirmée.

   Les URI de redirection doivent correspondre caractère pour caractère. Ce sont des adresses https:// absolues sans fragment ; le http:// simple n’est accepté que vers localhost ou une adresse de bouclage, pour le développement et les applications natives.

2. 2

   Générez un code_verifier aléatoire et envoyez le navigateur de la personne vers /oauth/authorize avec son SHA-256 comme code_challenge :

   shell

   # Un vérificateur : 43 à 128 caractères non réservés. Gardez-le jusqu’à l’échange.
   CODE_VERIFIER=$(openssl rand -base64 64 | tr -dc 'A-Za-z0-9' | cut -c1-64)
   CODE_CHALLENGE=$(printf '%s' "$CODE_VERIFIER" | openssl dgst -sha256 -binary \
     | openssl base64 -A | tr '+/' '-_' | tr -d '=')
   
   https://api.thecubefloor.com/oauth/authorize?response_type=code
     &client_id=app_…
     &redirect_uri=https%3A%2F%2Fyour.app%2Fcallback
     &scope=account%3Aread%20jobs%3Aread
     &state=…
     &code_challenge=$CODE_CHALLENGE
     &code_challenge_method=S256

   Copier
3. 3

   Elle voit notre page de consentement sur thecubefloor.com, avec le nom de votre application, ce qu’elle demande et où elle reviendra. Si elle accepte, le navigateur revient sur votre URI de redirection avec code et votre state ; si elle refuse, avec error=access_denied.

4. 4

   Échangez le code, dans la minute et une seule fois, contre des jetons. Authentifiez-vous en HTTP Basic ou avec client_id et client_secret dans le formulaire :

   shell

   curl https://api.thecubefloor.com/oauth/token \
     -u "$CLIENT_ID:$CLIENT_SECRET" \
     -d grant_type=authorization_code \
     -d code="$CODE" \
     -d redirect_uri=https://your.app/callback \
     -d code_verifier="$CODE_VERIFIER"

   Copier
5. 5

   La réponse contient un jeton d’accès (do_…, valable une heure) et un jeton de rafraîchissement (dr_…, trente jours). Chaque rafraîchissement consomme le jeton de rafraîchissement et renvoie une nouvelle paire ; présenter un jeton déjà consommé met fin à tous les jetons issus du même accord, car l’un de ses deux détenteurs est un voleur.

   json · shell

   {
     "access_token": "do_…",
     "token_type": "Bearer",
     "expires_in": 3600,
     "refresh_token": "dr_…",
     "scope": "account:read jobs:read"
   }
   
   curl https://api.thecubefloor.com/oauth/token \
     -u "$CLIENT_ID:$CLIENT_SECRET" \
     -d grant_type=refresh_token \
     -d refresh_token="$REFRESH_TOKEN"

   Copier
6. 6

   Quand la personne se déconnecte dans votre application, rendez le jeton (RFC 7009). Un jeton de rafraîchissement met fin à tout l’accord :

   shell

   curl https://api.thecubefloor.com/oauth/revoke \
     -u "$CLIENT_ID:$CLIENT_SECRET" \
     -d token="$REFRESH_TOKEN"

   Copier