Authentification

L’API de Stratt vit sur https://api.stratt.fr. Toute requête à une route métier porte deux choses, et elles ne se remplacent pas l’une l’autre : une identité et une organisation.

L’identité dit qui appelle. L’organisation dit dans quel périmètre. Un appel qui n’en porte qu’une est refusé — et les deux refus ne portent pas le même code, ce que la page Erreurs détaille.

L’identité : deux façons

Jeton de session

C’est la façon que l’application elle-même emploie, et celle sur laquelle une intégration peut s’appuyer aujourd’hui.


Authorization: Bearer <jeton-d-acces>

Le jeton s’obtient en échangeant des identifiants :


curl -s https://api.stratt.fr/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"…","password":"…"}'

La réponse porte un jeton d’accès (access_token), de courte durée, et un jeton de rafraîchissement (refresh_token) qui sert à en obtenir un nouveau sur POST /api/v1/auth/refresh. GET /api/v1/auth/me renvoie le profil du compte connecté, et POST /api/v1/auth/logout met fin à la session.

La fin de session est effective côté serveur : un jeton d’accès dont la session n’existe plus est refusé, même s’il n’a pas encore atteint son terme. Une déconnexion n’est donc pas un simple oubli côté client.

L’organisation


X-Organization-Id: <uuid-de-l-organisation>

Cet en-tête est requis sur les routes métier. Il n’est pas un confort d’affichage : c’est lui qui désigne le périmètre dans lequel la requête est servie. Les identifiants d’organisation auxquels un compte appartient se lisent sur GET /api/v1/organizations.

Trois cas, trois réponses différentes :

Ce que porte la requête	Réponse
aucun en-tête d’organisation	`400` — l’en-tête est réclamé
une organisation mal formée	`400` — l’identifiant n’est pas un UUID
une organisation dont vous n’êtes pas membre	`403` — appartenance refusée

Une ressource qui existe mais appartient à une autre organisation que celle de l’en-tête, en revanche, répond 404 : du point de vue de la requête, elle n’existe pas. Voir Erreurs, section « 404 ».

Un exemple complet


curl -s https://api.stratt.fr/api/v1/mandats \
  -H "Authorization: Bearer $STRATT_TOKEN" \
  -H "X-Organization-Id: $STRATT_ORG_ID"

Jamais de justificatif dans l’URL

Ne mettez aucun justificatif d’identité dans une URL. Ce n’est pas une préférence de style : une URL finit dans les journaux du serveur, dans l’historique du navigateur, et dans l’en-tête Referer envoyé à toute ressource distante que la page appelle.

Sur les routes qui servent des documents — rapports, fiches, exports — l’API applique cette règle elle-même : une URL portant un jeton de session y est refusée, avec une page qui explique de rouvrir le document depuis l’application. Ces documents s’ouvrent par un lien à usage unique obtenu sur POST /api/v1/exports/ticket, décrit dans la Référence, section sur les documents.

Depuis un navigateur

Une application web tierce est soumise à la politique d’origine croisée de l’API, qui n’accepte que trois en-têtes de requête :


Content-Type
Authorization
X-Organization-Id

Un en-tête supplémentaire fera échouer la requête préalable du navigateur, avant même que l’API ne la voie. Les intégrations serveur à serveur ne sont pas concernées.

Limites de débit

Il n’y a pas une limite unique mais deux, et elles ne portent pas sur la même chose :

Les routes de connexion

/api/v1/auth/… est plafonné par adresse IP, avec une tolérance de courte durée pour les rafales. Au-delà, l’API répond 429 avec un en-tête Retry-After. Ce plafond existe contre l’essai de mots de passe en série ; une intégration normale ne l’atteint pas, puisqu’elle rafraîchit un jeton au lieu de se reconnecter.

Les appels par clé d’API

1 000 requêtes par heure, comptées par clé. Au-delà, l’API répond 429 et le message le dit.

Les appels portant un jeton de session ne sont, eux, pas plafonnés au-delà des routes de connexion. Ce n’est pas une invitation à interroger en boucle : si votre intégration consulte l’API pour détecter un changement, un webhook la préviendra.

Permissions requises

S’authentifier n’en exige aucune. En revanche, chaque route métier contrôle ensuite deux choses, dans cet ordre : que l’organisation ait souscrit au module dont relève la route, puis que le compte détienne la permission qu’elle réclame. Ces deux refus sont distincts et se résolvent différemment — c’est l’objet de la page Erreurs.