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 :
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.
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/1.1 401 Unauthorized
content-type: application/problem+json
www-authenticate: Bearer realm="noryo-merchant-api", error="invalid_token"
noryo-request-id: req_…{
"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.
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 | 403 | L'organisation ou le workspace de la clé n'est pas actif |
production_not_enabled | 403 | La clé n'est pas autorisée à appeler la Production |
insufficient_scope | 403 | La clé n'a pas le scope de la route |
Dans cette section
- Clés API : anatomie, création et liste des clés.
- Environnements : Sandbox et Production, ce qui est isolé.
- Sécurité des secrets : où vit le secret, ce que Noryo en garde.
- Rotation : remplacer une clé sans interruption.
- Révocation : couper une clé, et ce qui survit.
Publié le 2026-10-08 21:04 UTC (version 1).