Référence API

Authentification OAuth2

CrowAccounts implémente le flux Authorization Code d'OAuth2. Cette page détaille chaque endpoint ; pour une intégration pas à pas, commence par le démarrage rapide.

Sur cette page

GET /oauth/authorize
POST /oauth/token (authorization_code)
POST /oauth/token (refresh_token)
GET /oauth/userinfo
POST /oauth/revoke
Durée de vie des jetons

GET /oauth/authorize

GET /oauth/authorize Point d'entrée du "Se connecter avec CrowAccounts" — à ouvrir dans le navigateur de l'utilisateur, jamais en appel serveur à serveur.

Paramètre	Description
`client_id`requis	L'identifiant de ton application.
`redirect_uri`requis	Doit correspondre exactement (schéma, hôte, chemin) à l'une des URIs enregistrées pour ton app. Aucune correspondance partielle n'est acceptée.
`response_type`requis	Doit valoir `code` — c'est le seul flux supporté.
`scope`optionnel	Liste de scopes séparés par des espaces (ex. `profile email`). Par défaut : `profile`. Voir Scopes & profil.
`state`optionnel	Valeur opaque que tu fournis et qui t'est renvoyée telle quelle. Fortement recommandé pour te protéger du CSRF — voir Sécurité.
`code_challenge`requis	PKCE (RFC 7636) — obligatoire pour toutes les applications, y compris celles avec un client_secret. Sans lui, `/oauth/authorize` refuse la requête. Voir Sécurité.
`code_challenge_method`optionnel	`S256` (recommandé) ou `plain`. Par défaut `plain` si omis — préfère toujours `S256` quand c'est possible : `plain` n'apporte aucune protection contre l'interception du code en transit.

Comportement

Si client_id/redirect_uri ne correspond à aucune application active, CrowAccounts affiche directement une page d'erreur — il ne redirige jamais vers une redirect_uri non enregistrée.
Si l'utilisateur n'est pas connecté, il est renvoyé vers l'écran de connexion, puis ramené ici automatiquement une fois connecté.
Le scope réellement accordé est l'intersection entre ce que tu demandes ici et les scopes que ton app a le droit de demander (déclarés à sa création — voir Gérer son application).
Si l'utilisateur a déjà tout accordé par le passé (même scope ou plus large), le code est généré immédiatement sans réafficher l'écran de consentement. Si tu demandes un scope jamais accordé avant, l'écran de consentement réapparaît — un scope ne s'élargit jamais silencieusement.

Retour, dans les deux cas, sous forme de redirection vers ta redirect_uri : ?code=...&state=... en cas d'accord, ou ?error=access_denied&state=... en cas de refus.

POST /oauth/token grant_type=authorization_code

POST /oauth/token Appel serveur à serveur uniquement — exige ton client_secret. Limité à 30 requêtes/min par client_id.

Paramètre	Description
`grant_type`requis	Doit valoir `authorization_code`.
`code`requis	Le code reçu à l'étape précédente. À usage unique, valide 5 minutes.
`client_id`requis	Ton identifiant d'application.
`client_secret`requis	Ton secret d'application.
`redirect_uri`requis	Doit être identique, caractère pour caractère, à celle utilisée dans l'appel à `/oauth/authorize`.
`code_verifier`requis	Doit permettre de retrouver le `code_challenge` envoyé à `/oauth/authorize` pour ce login (PKCE, obligatoire pour toutes les applications). L'échange échoue avec `invalid_grant` s'il est absent ou incorrect.

Réponse (200) :

json

{
  "access_token": "...",
  "refresh_token": "...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "profile email"
}

Un code déjà utilisé, expiré, ou dont le client_id/redirect_uri ne correspond pas exactement à ceux avec lesquels il a été émis renvoie invalid_grant — voir Erreurs & limites.

POST /oauth/token grant_type=refresh_token

POST /oauth/token Renouvelle un access_token expiré sans repasser par l'utilisateur.

Paramètre	Description
`grant_type`requis	Doit valoir `refresh_token`.
`refresh_token`requis	Ton refresh_token le plus récent.
`client_id`requis	Ton identifiant d'application.
`client_secret`requis	Ton secret d'application.

Rotation et détection de vol

Chaque appel réussi invalide l'ancien refresh_token et en émet un nouveau, rattaché à la même "famille" de jetons. Ça permet de détecter un vol : si un refresh_token déjà consommé est présenté à nouveau (par exemple parce qu'une copie volée traîne encore quelque part), CrowAccounts en déduit qu'il y a eu fuite et révoque immédiatement toute la famille — access_token compris.

Que faire si ça t'arrive

Une réponse invalid_grant avec le message "Refresh token déjà utilisé" signifie que la session entière a été coupée par sécurité. Il n'y a rien à réparer côté jeton : renvoie l'utilisateur en authentification complète.

Réponse en cas de succès : identique au format de l'échange initial (nouveau access_token + nouveau refresh_token).

GET /oauth/userinfo

GET /oauth/userinfo Header requis : Authorization: Bearer <access_token>

Renvoie les champs correspondant au scope accordé pour ce jeton précis. Le détail complet (quels champs pour quel scope, sémantique de email_verified) est sur la page Scopes & profil utilisateur.

Un jeton absent, invalide ou expiré renvoie 401 { "error": "invalid_token" }.

POST /oauth/revoke

POST /oauth/revoke Suit RFC 7009. Limité à 30 requêtes/min par client_id (même compteur que /oauth/token).

À utiliser quand ton propre utilisateur se déconnecte de ton application, pour couper le jeton côté CrowAccounts plutôt que de le laisser vivre jusqu'à expiration naturelle.

Paramètre	Description
`token`requis	Le jeton (access ou refresh) à révoquer.
`token_type_hint`optionnel	`access_token` ou `refresh_token` — accélère la recherche, mais n'est qu'une indication : les deux tables sont vérifiées si besoin.
`client_id`requis	Ton identifiant d'application.
`client_secret`requis	Ton secret d'application.

Révoquer un refresh_token supprime aussi immédiatement l'access_token émis avec, au lieu de le laisser courir jusqu'à sa propre expiration.

Toujours 200

Comme le recommande la RFC, cet endpoint répond systématiquement { "revoked": true }, que le jeton existe, soit déjà expiré, déjà révoqué, ou totalement inconnu. Ce n'est pas un moyen de vérifier si un jeton est valide.

Durée de vie des jetons

Jeton	Durée de vie
Code d'autorisation	5 minutes, usage unique
`access_token`	1 heure
`refresh_token`	30 jours (renouvelé à chaque rotation)