# Clés API

> L'anatomie d'une clé Merchant API, sa création dans Platform, le secret affiché une seule fois, les scopes, et ce que plusieurs clés d'un même workspace partagent.

Une clé Merchant API est une chaîne unique qui porte son environnement, un identifiant public et un secret. Elle appartient à un workspace et porte des scopes.

## Anatomie

```text
nry_mer_sbx_7XKD2M9QPA.<secret>
└──────────┘└────────┘ └──────┘
  préfixe     key_id     secret
```

| Partie | Rôle | Secret ? |
|---|---|---|
| `nry_mer_sbx_` ou `nry_mer_live_` | Famille de l'API et environnement | non |
| `key_id` | Identifiant public de la clé : 10 caractères de `23456789ABCDEFGHJKMNPQRSTVWXYZ`, majuscules uniquement | non |
| secret | 32 octets aléatoires encodés en Base64URL sans remplissage, soit 43 caractères | **oui** |

L'alphabet du `key_id` exclut les caractères ambigus (`0`, `O`, `1`, `I`, `L`, `U`) : une clé recopiée à la main ne peut pas devenir en silence une autre clé. La casse n'est jamais corrigée : un `key_id` en minuscules est refusé. Le `key_id` ci-dessus est un exemple de forme, pas une clé réelle.

## Créer une clé

Les clés Sandbox se créent dans la page [Clés d'API](https://platform.noryo.app/keys) de Platform.

1. Connectez-vous à Platform avec votre identité Noryo et choisissez votre workspace.
2. Donnez un nom à la clé (par exemple `intégration de test`).
3. Cochez les scopes : `enrich:read`, `enrich:write`, ou les deux (par défaut, les deux).
4. Créez la clé, puis **copiez le secret immédiatement**.

> **Important** Le secret n'est affiché qu'une seule fois, à la création, et n'est jamais récupérable. Noryo ne le stocke pas : seul un vérificateur dérivé du secret est conservé. Un secret perdu se remplace, il ne se retrouve pas. Voir [Rotation](https://developer.noryo.app/fr-FR/merchant/authentication/rotation).

Tant que Noryo n'a pas ouvert l'émission de clés Sandbox, la création est refusée par le serveur avec le message `Sandbox access is not enabled yet.`. Platform n'émet que des clés Sandbox : elle n'offre aucun moyen de créer une clé de Production, qui ne peut exister qu'une fois votre dossier approuvé. Voir [Passage en production](https://developer.noryo.app/fr-FR/merchant/going-live).

Tout membre de l'organisation peut créer et révoquer les clés de ses workspaces.

## La liste des clés

La même page liste les clés du workspace :

| Colonne | Contenu |
|---|---|
| nom | Le nom donné à la création |
| `key_id` | L'identifiant public |
| clé | Le préfixe suivi des quatre derniers caractères du `key_id` (`nry_mer_sbx_…9QPA`) |
| scopes | `enrich:read`, `enrich:write` |
| créée, dernier usage | Dates de création et de dernière utilisation |
| état | `active` ou `revoquee` |

Le secret n'y figure jamais : il n'existe nulle part chez Noryo.

## Scopes

| Scope | Autorise |
|---|---|
| `enrich:read` | Relire un résultat (`GET`) |
| `enrich:write` | Créer un enrichissement et le rafraîchir (`POST`) |

Une clé qui ne fait qu'écrire n'a pas besoin de `enrich:read`, et inversement. Une route appelée sans son scope rend `403 insufficient_scope`.

## Plusieurs clés dans un même workspace

| Partagé entre les clés d'un workspace (par environnement) | Propre à chaque clé |
|---|---|
| Les résultats : toute clé du workspace et du même environnement peut relire un `enrichment_id`, quelle que soit la clé qui l'a créé | Le seau de débit |
| L'espace des `Idempotency-Key` | Les scopes |
| La déduplication par `external_transaction_id` | La révocation |

Conséquence pratique : deux services qui partagent un workspace partagent aussi l'espace des clés d'idempotence. Préfixez vos `Idempotency-Key` par service, ou générez-les de façon unique. Voir [Idempotence](https://developer.noryo.app/fr-FR/merchant/requests/idempotency).

---

Page canonique : https://developer.noryo.app/fr-FR/merchant/authentication/api-keys