# Authentification

> Comment présenter une clé API, ce que le serveur vérifie, pourquoi toute clé refusée rend le même 401, et quels scopes ouvrent quelles routes.

Chaque requête s'authentifie par une clé API envoyée dans l'en-tête `Authorization`, selon le schéma `Bearer` :

```http
Authorization: Bearer nry_mer_sbx_<key_id>.<secret>
```

Il n'existe pas d'autre mode d'authentification : pas de paramètre d'URL, pas de champ de corps, pas de jeton à échanger.

## La forme de l'en-tête

Le serveur lit l'en-tête strictement :

- le nom du schéma est insensible à la casse (`Bearer`, `bearer`, `BEARER`) ;
- un seul espace sépare le schéma de la clé ;
- aucun espace, tabulation ou retour à la ligne avant, après ou dans la clé ;
- aucun autre schéma n'est accepté.

Toute autre forme est refusée en `401`. Le serveur ne corrige rien, ne rogne rien et ne change pas la casse.

## La forme de la clé

| Partie | Valeur |
|---|---|
| Préfixe | `nry_mer_sbx_` (Sandbox) ou `nry_mer_live_` (Production) |
| `key_id` | 10 caractères de l'alphabet `23456789ABCDEFGHJKMNPQRSTVWXYZ`, en majuscules |
| Séparateur | un point `.` |
| Secret | Base64URL sans remplissage ; une clé émise par Noryo porte un secret de 43 caractères |

Le préfixe annonce l'environnement, mais il n'est jamais l'autorité : le serveur confirme l'environnement de la clé enregistrée et refuse une clé dont le préfixe déclaré ne correspond pas. Une clé d'une autre API Noryo est refusée sur celle-ci, même parfaitement formée. Voir [Clés API](https://developer.noryo.app/fr-FR/merchant/authentication/api-keys).

## Un seul code pour toute clé refusée

Clé absente, mal formée, inconnue, révoquée, préfixe d'environnement erroné : la réponse est **toujours** la même.

```http
HTTP/1.1 401 Unauthorized
content-type: application/problem+json
www-authenticate: Bearer realm="noryo-merchant-api", error="invalid_token"
noryo-request-id: req_…
```

```json
{
  "type": "https://developer.noryo.app/errors/invalid_api_key",
  "title": "Invalid API credential",
  "status": 401,
  "code": "invalid_api_key",
  "detail": "The API credential is missing, malformed, revoked, or unknown.",
  "request_id": "req_…"
}
```

Toute distinction dirait à un attaquant laquelle des deux moitiés de sa supposition était juste. Un `401` ne consomme aucun jeton de débit. Voir [invalid_api_key](https://developer.noryo.app/fr-FR/errors/invalid_api_key).

## Scopes

Une clé porte des scopes, choisis à sa création.

| Scope | Routes |
|---|---|
| `enrich:read` | `GET /merchant/v1/enrichments/{enrichment_id}` |
| `enrich:write` | `POST /merchant/v1/enrichments` et `POST /merchant/v1/enrichments/{enrichment_id}/refresh` |

Une clé valide sans le scope requis reçoit `403 insufficient_scope`, avec l'en-tête `WWW-Authenticate: Bearer realm="noryo-merchant-api", error="insufficient_scope"`. Ce refus intervient après le contrôle de débit : il consomme un jeton.

## Autres refus d'autorisation

| Code | Statut | Quand |
|---|---|---|
| [`account_inactive`](https://developer.noryo.app/fr-FR/errors/account_inactive) | 403 | L'organisation ou le workspace de la clé n'est pas actif |
| [`production_not_enabled`](https://developer.noryo.app/fr-FR/errors/production_not_enabled) | 403 | La clé n'est pas autorisée à appeler la Production |
| [`insufficient_scope`](https://developer.noryo.app/fr-FR/errors/insufficient_scope) | 403 | La clé n'a pas le scope de la route |

## Dans cette section

- [Clés API](https://developer.noryo.app/fr-FR/merchant/authentication/api-keys) : anatomie, création et liste des clés.
- [Environnements](https://developer.noryo.app/fr-FR/merchant/authentication/environments) : Sandbox et Production, ce qui est isolé.
- [Sécurité des secrets](https://developer.noryo.app/fr-FR/merchant/authentication/secret-security) : où vit le secret, ce que Noryo en garde.
- [Rotation](https://developer.noryo.app/fr-FR/merchant/authentication/rotation) : remplacer une clé sans interruption.
- [Révocation](https://developer.noryo.app/fr-FR/merchant/authentication/revocation) : couper une clé, et ce qui survit.

---

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