Authentification & jetons d’API

Principe

Chaque appel à l’API REST s’authentifie par un jeton d’API (access token) placé dans l’en-tête Authorization :

Authorization: Bearer act_<id>.<secret>

Le jeton d’API est rattaché à un utilisateur de votre tenant et agit avec ses droits. Les droits d’un utilisateur sont ceux de son groupe (un groupe peut ne compter qu’un seul utilisateur, si besoin) : le rôle de développement Développeur autorise précisément la création de ses propres jetons d’API (ainsi que de ses propres webhooks). Voir la fondation Groupes, rôles & droits. Un même jeton d’API suffit ensuite à toutes les opérations autorisées : provisionnement, parapheurs, documents, preuves…

Règle de sécurité — Un jeton d’API est un secret. Il doit être utilisé exclusivement depuis le backend de votre application, jamais exposé au navigateur, à une application mobile, ni déposé dans un dépôt de code.

Créer un jeton d’API

POST /api/users/{userId}/accessTokens
Authorization: Bearer act_<id>.<secret>
Content-Type: application/json
{
  "name": "Intégration back-office",
  "authorizedIpRanges": [ "10.0.0.0/8", "192.168.1.0/24" ]
}

L’appel est authentifié par un jeton d’API existant ou des identifiants administrateur.

La réponse renvoie le jeton d’API créé :

{
  "id": "act_5JDLegodEqQW7FhQBpCHHdrX",
  "tenantId": "ten_…",
  "userId": "usr_…",
  "name": "Intégration back-office",
  "authorizedIpRanges": [ "10.0.0.0/8", "192.168.1.0/24" ],
  "tokenValue": "act_5JDLegodEqQW7FhQBpCHHdrX.2gP4K5umX6kv…",
  "created": 1782821510314,
  "updated": 1782821510314
}

⚠️ tokenValue n’est renvoyé qu’à la création. C’est la seule et unique fois où la valeur complète (act_<id>.<secret>) est communiquée : elle n’est jamais retournée par la suite. Conservez-la immédiatement dans un coffre à secrets ou une variable d’environnement du backend. En cas de perte, créez un nouveau jeton d’API et supprimez l’ancien (section Cycle de vie d’un jeton d’API).

Restreindre l’usage par adresse IP

Le champ authorizedIpRanges est facultatif : si vous ne le renseignez pas, toutes les adresses IP sont autorisées. Pour restreindre l’usage du jeton d’API — par exemple aux adresses de vos serveurs backend — indiquez une liste d’adresses IPv4 et/ou de plages en notation CIDR :

"authorizedIpRanges": [ "192.168.1.0/24", "127.0.0.1", "206.3.5.0/16" ]

C’est une protection recommandée : même divulgué, le jeton d’API reste inutilisable hors de ces adresses.

Cycle de vie d’un jeton d’API

• Consulter — GET /api/accessTokens/{id} (la valeur tokenValue n’y figure pas).
• Modifier — PATCH /api/accessTokens/{id} pour changer le name ou les authorizedIpRanges (voir la concurrence optimiste If-Match, fondation Structure > Concurrence : l’en-tête conditionnel If-Match).
• Révoquer — DELETE /api/accessTokens/{id}.
• Lister — GET /api/accessTokens (recherche et filtres, fondation Structure > Recherche & pagination).

Erreurs de création

Bonnes pratiques

• Backend uniquement ; jamais côté client ni en dépôt de code.
• Stockage en coffre à secrets ou variable d’environnement.
• Restreindre par authorizedIpRanges.
• Un jeton d’API nommé par usage (application, environnement), révocable indépendamment.
• Prévoir une rotation : créer le nouveau jeton d’API, basculer, puis supprimer l’ancien.