Authentification

Chaque requête vers /api/v1/* doit porter un jeton bearer :

Authorization: Bearer <jeton>
Accept: application/json

Deux façons d'en obtenir un, pour deux cas d'usage différents.

Jetons API d'organisation (serveur à serveur)#

Le chemin le plus simple pour les intégrations : créez un jeton dans le panneau d'administration, sous Organisation → Jetons API.

• Le jeton n'est affiché qu'une seule fois à la création — conservez-le en lieu sûr.
• Il est lié à une seule organisation ; inutile de sélectionner une organisation à chaque requête, mais si vous envoyez X-Organization-Id, il doit correspondre à l'organisation du jeton.
• Chaque jeton porte ses propres scopes (voir plus bas ; * accorde tout).
• Un jeton peut recevoir une date d'expiration et se révoque depuis la même page d'administration (pas via le point de terminaison de déconnexion).

OAuth 2.0 Authorization Code + PKCE (applications agissant pour des utilisateurs)#

Pour les applications où un utilisateur se connecte avec son propre compte EncryptInvoice, utilisez le flux standard OAuth 2.0 Authorization Code avec PKCE. C'est un flux client public — il n'y a pas de secret client.

1. Générez un code_verifier (aléatoire, 43–128 caractères) et son code_challenge (Base64url(SHA-256(verifier))), plus un state aléatoire.
2. Ouvrez le navigateur système sur :

GET /oauth/authorize
    ?client_id=<client_id>
    &redirect_uri=<URI de redirection enregistrée>
    &response_type=code
    &scope=<scopes séparés par des espaces>
    &state=<state>
    &code_challenge=<code_challenge>
    &code_challenge_method=S256

3. Après connexion, le navigateur est redirigé vers votre redirect_uri avec ?code=...&state=.... Vérifiez state, puis échangez le code :

POST /oauth/token
grant_type=authorization_code
client_id=<client_id>
redirect_uri=<même URI de redirection>
code=<code>
code_verifier=<verifier d'origine>

Réponse :

{
  "token_type": "Bearer",
  "expires_in": 1296000,
  "access_token": "eyJ0eXAiOiJKV1Q...",
  "refresh_token": "def50200..."
}

Rafraîchissement#

POST /oauth/token
grant_type=refresh_token
refresh_token=<refresh_token>
client_id=<client_id>

La rotation est active : chaque rafraîchissement renvoie un nouveau jeton d'accès et un nouveau refresh token, et révoque l'ancien. Remplacez la paire stockée de manière atomique ; un 400 invalid_grant signifie que la session est terminée — relancez le flux de connexion.

Déconnexion#

La révocation est immédiate. Les jetons API d'organisation se gèrent dans le panneau d'administration et renvoient 400 invalid_token_type sur ces points de terminaison.

Scopes#

Les scopes déclarent l'intention de votre application ; l'autorisation réelle est de plus contrôlée par utilisateur et par rôle à chaque requête. Un jeton ne peut jamais faire plus que ce que l'utilisateur ou l'organisation derrière lui est autorisé à faire.

Durées de vie des jetons#