> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.goodflag.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.goodflag.com/_mcp/server.

# Authentification

> Jetons d'API : principe, création, restriction IP, cycle de vie, erreurs, bonnes pratiques

# 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` :

```http
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*](/wm/api-reference/concepts/groupes-roles-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

```http
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**.

| Champ                | Type   | Rôle                                                                                                                                 |
| -------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| `name`               | String | Libellé du jeton d'API (pour le reconnaître et le gérer).                                                                            |
| `authorizedIpRanges` | Array  | *(facultatif)* Adresses IPv4 et/ou plages CIDR autorisées à utiliser le jeton d'API. **Omis → toutes les adresses sont autorisées.** |

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

```json
{
  "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*](#cycle-de-vie-dun-jeton-dapi)).

## 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** :

```json
"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`*](/wm/api-reference/structure#concurrence-len-tete-conditionnel-if-match)).
* **Révoquer** — `DELETE /api/accessTokens/{id}`.
* **Lister** — `GET /api/accessTokens` (recherche et filtres, fondation [*Structure > Recherche & pagination*](/wm/api-reference/structure#recherche-pagination)).

## Erreurs de création

| HTTP | `code`                      | Signification                                                   |
| ---- | --------------------------- | --------------------------------------------------------------- |
| 400  | `InvalidRequestField`       | Un champ de la requête a une valeur incorrecte.                 |
| 403  | `AuthenticatedUserDisabled` | L'utilisateur authentifié est désactivé.                        |
| 403  | `MissingBearerToken`        | Aucun jeton d'API n'a été fourni (en-tête `Bearer`).            |
| 403  | `TenantInactive`            | Le tenant est inactif et n'autorise aucune opération.           |
| 403  | `UserGroupDisabled`         | Le groupe de l'utilisateur visé est désactivé.                  |
| 403  | `UserNotAllowed`            | L'utilisateur authentifié n'est pas autorisé à cette opération. |

## 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.