# Obtenir des identifiants

> Les trois identités qu'une opération peut exiger, et comment les présenter. Le contrat de l'API dit lesquelles chaque opération accepte (security). Côté…

Guide - Depuis la version 0.3.0 - Flexway v1.6.3 - https://flexway.io/docs/developer-credentials/

> Les trois identités qu'une opération peut exiger, et comment les présenter. Le contrat de l'API dit lesquelles chaque opération accepte (`security`).
>
> Côté produit : [Identité et zéro confiance](https://flexway.io/docs/product-identity/) ; côté exploitation : [Brancher son fournisseur d'identité](https://flexway.io/docs/operations-identity/), [Clés d'API](https://flexway.io/docs/operations-api-keys/), [Certificats clients (mTLS)](https://flexway.io/docs/operations-client-certificates/).

## Quel identifiant pour quel cas

| Vous êtes | Identifiant | Présenté par |
| --- | --- | --- |
| Une application qui agit pour une personne, ou un service | **Jeton OIDC** du fournisseur d'identité de l'exploitant | `Authorization: Bearer <jeton>` |
| Une intégration connue sans utilisateur (partenaire, batch) | **Clé d'API** remise par l'exploitant | `Authorization: ApiKey <clé>` |
| Un serveur partenaire | **Certificat client** (mTLS) déclaré par l'exploitant | La poignée de main TLS |
| Un agent IA (MCP) | Jeton OIDC émis pour la surface MCP | Voir [MCP](https://flexway.io/docs/developer-mcp/) |

Votre **tenant** (le client que vous représentez) vient toujours de l'identifiant : une claim du jeton,
la clé ou le certificat. Un en-tête de tenant que vous écrivez n'atteint jamais l'API.

## Jeton OIDC

Demandez un jeton au fournisseur d'identité de l'exploitant, pour l'**audience** de l'API et avec les
**portées** que le contrat exige. Pour un service sans utilisateur, le flux *client credentials* :

```bash
TOKEN=$(curl -s https://login.example.com/oauth2/token \
  -d grant_type=client_credentials -d client_id=billing -d client_secret="$SECRET" \
  -d scope="orders:read" -d audience=api | jq -r .access_token)
curl -H "Authorization: Bearer $TOKEN" https://api.example.com/orders/42
```

Le nom exact du paramètre d'audience dépend du fournisseur (`audience`, `resource`, une portée
dédiée) ; l'exploitant vous donne l'URL du fournisseur, l'audience et les portées.

## Clé d'API

| Règle | Détail |
| --- | --- |
| Format | `fwk_` suivi de 43 caractères ; montrée **une seule fois** à sa création |
| En-tête | `Authorization: ApiKey <clé>` seulement - jamais `X-Api-Key`, jamais dans l'URL (ignorée) |
| Portée | Liée à **un** tenant, à des **opérations nommées** et à une **date de fin** |
| Rotation | L'exploitant émet une seconde clé, vous basculez, l'ancienne est retirée |
| Débit | Compté par clé |

```bash
curl -H "Authorization: ApiKey $FLEXWAY_KEY" https://api.example.com/invoices
```

## Certificat client

```bash
curl --cert client.crt --key client.key https://api.example.com/settlements -X POST -d @settle.json
```

Le certificat est déclaré par l'exploitant (de préférence par son URI SAN, qui survit au
renouvellement) et lié à un tenant et à des opérations.

## Ce que vous recevez

| Situation | Réponse |
| --- | --- |
| Aucun identifiant | `401`, `WWW-Authenticate: Bearer` |
| Jeton invalide, expiré, d'un autre émetteur ou d'une autre audience | `401`, `error="invalid_token"` - jamais la raison exacte |
| Jeton valide sans la portée | `403`, `error="insufficient_scope", scope="..."` |
| Clé inconnue, expirée ou sans le préfixe `fwk_` | `401`, `WWW-Authenticate: ApiKey` |
| Clé valide sur une opération qu'elle ne nomme pas | `403` |
| Certificat non déclaré, ou aucun | `401` |
| Jeton sur une opération qui n'accepte que `mutualTLS` | `401` |

Un jeton ne remplace jamais une clé, ni l'inverse : le contrat dit quelle alternative chaque opération
accepte.