Okouro s’authentifie avec des JSON Web Tokens (JWT). Vous échangez vos identifiants contre un jeton d’accès et un jeton de rafraîchissement, envoyez le jeton d’accès à chaque requête, et utilisez le jeton de rafraîchissement pour obtenir une nouvelle paire quand le jeton d’accès expire. Les jetons sont signés avec RS256.

La paire de jetons

Une connexion, une inscription ou un rafraîchissement réussi renvoie un AuthResponse :

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "user": { "...": "see /auth/me below" }
}

• Le jeton d’accès authentifie les appels API normaux. Il est de courte durée (1 heure par défaut).
• Le jeton de rafraîchissement génère une nouvelle paire. Il est de plus longue durée (24 heures par défaut).

La réponse n’inclut pas de champ expires_in. Les durées de vie des jetons sont fixées par la configuration du serveur, donc considérez un jeton d’accès comme valide pendant environ une heure et rafraîchissez-le de façon proactive (voir Rafraîchir).

Inscription

L’inscription se fait en deux étapes : soumettez votre e-mail professionnel pour recevoir un lien, puis ouvrez le lien pour créer votre entreprise et son compte administrateur.

Étape 1 - Demander un lien d’inscription.

POST /auth/signup HTTP/1.1
Content-Type: application/json

{
  "email": "you@acme.com"
}

Renvoie toujours 200 OK, que l’adresse soit disponible ou non, de sorte qu’elle ne peut pas servir à deviner quelles adresses sont inscrites. Quand l’adresse est disponible, un lien d’inscription lui est envoyé par e-mail.

Étape 2 - Terminer l’inscription depuis le lien.

POST /auth/complete-signup HTTP/1.1
Content-Type: application/json

{
  "token": "<token from the emailed link>",
  "account_name": "Acme Consulting",
  "first_name": "Alex",
  "last_name": "Martin",
  "password": "a-strong-password"
}

Renvoie 200 OK avec un AuthResponse et connecte le nouvel administrateur. Le mot de passe doit comporter au moins 8 caractères. Un jeton invalide ou expiré renvoie 400 Bad Request ; une adresse e-mail déjà inscrite renvoie 409 Conflict.

Se connecter

POST /auth/login HTTP/1.1
Content-Type: application/json

{
  "email": "you@acme.com",
  "password": "your-password"
}

Renvoie 200 OK avec un AuthResponse. Des identifiants erronés renvoient 401 Unauthorized.

En plus du corps, le serveur définit un cookie HttpOnly nommé okouro_refresh (restreint à Path=/auth) qui porte le jeton de rafraîchissement. Les navigateurs s’appuient sur ce cookie pour le rafraîchissement ; les intégrations serveur à serveur peuvent l’ignorer et conserver à la place le refresh_token du corps.

Présenter le jeton d’accès

Envoyez le jeton d’accès comme jeton porteur sur chaque requête protégée :

GET /users HTTP/1.1
Authorization: Bearer <access_token>

Un jeton manquant ou invalide renvoie 401 Unauthorized. Un jeton valide dont le rôle n’est pas autorisé pour le point de terminaison renvoie 403 Forbidden (voir Rôles et permissions).

Qui suis-je

GET /auth/me renvoie l’utilisateur courant sous forme de UserResponse nu (et non enveloppé dans un AuthResponse) :

{
  "id": "0190a1c2-3d4e-7f80-9a1b-2c3d4e5f6a7b",
  "account_id": "0190a1c2-0000-7f80-9a1b-2c3d4e5f6a7b",
  "email": "you@acme.com",
  "first_name": "Alex",
  "last_name": "Martin",
  "role": "admin",
  "created_at": "2026-01-05T09:00:00Z",
  "consultant_id": null,
  "settings": { "language": "en" },
  "is_manager": false
}

consultant_id est défini quand l’utilisateur est relié à un profil de consultant ; c’est ce lien qui déverrouille les surfaces en libre-service de feuille de temps, d’affectation, de congés et de frais. is_manager est vrai quand l’utilisateur gère au moins un consultant (voir Rôles et permissions).

Rafraîchir

Quand le jeton d’accès expire, demandez une nouvelle paire. Le serveur lit d’abord le jeton de rafraîchissement depuis le cookie okouro_refresh, puis se rabat sur un corps JSON :

POST /auth/refresh HTTP/1.1
Content-Type: application/json

{
  "refresh_token": "<refresh_token>"
}

Renvoie 200 OK avec un AuthResponse neuf. Un jeton de rafraîchissement invalide, expiré ou déjà trop ancien renvoie 401 Unauthorized.

Le jeton de rafraîchissement est sans état : il ne peut pas être révoqué individuellement, et sa fenêtre d’exposition n’est bornée que par son propre TTL. Conservez-le avec autant de soin qu’un mot de passe.

Stratégie de rafraîchissement. Appelez /auth/refresh peu avant l’expiration du jeton d’accès plutôt que d’attendre un 401. Une approche simple : rafraîchissez quand une requête renvoie 401, rejouez-la une fois avec le nouveau jeton, et considérez un second 401 comme une déconnexion définitive.

Se déconnecter

POST /auth/logout HTTP/1.1
Authorization: Bearer <access_token>

Renvoie 204 No Content et efface le cookie okouro_refresh. Comme les jetons d’accès sont sans état, se déconnecter n’invalide pas un jeton d’accès encore dans son TTL ; cela vous empêche seulement de le rafraîchir. Supprimez aussi les jetons côté client.

Deux autres façons d’obtenir une session

Deux points de terminaison publics renvoient aussi un AuthResponse complet et définissent le cookie de rafraîchissement, car ils créent ou réinitialisent des identifiants :

• POST /invitations/accept - accepter une invitation connecte le nouvel utilisateur. Voir Gérer les personnes.
• POST /password-changes/redeem - utiliser un lien de changement de mot de passe connecte l’utilisateur avec le nouveau mot de passe.

Résumé