Authentification

Toute requête vers l'API Transaction Intelligence, à l'exception du contrat public GET /openapi.json, est authentifiée par une clé d'API portée dans l'en-tête Authorization. Cette page décrit le format de la clé, la façon de la présenter, l'endroit où garder son secret et la lecture des refus 401 et 403. La création pas à pas est décrite dans le Quickstart ; la lecture de l'usage par clé dans Usage et clés d'API.

Le format de la credential

Une clé Transaction Intelligence appartient à la famille txn. En sandbox, elle s'écrit :

nry_txn_sbx_<key_id>.<secret>

• nry_txn_sbx_ : le préfixe. Il déclare la famille (txn) et l'environnement (sbx, le sandbox).
• <key_id> : l'identifiant public de la clé, sur 10 caractères. C'est lui que Platform affiche dans la liste des clés et dans la page Usage ; il n'est pas secret.
• <secret> : la partie secrète, après le point. Elle n'est montrée qu'une fois.

Le contrat décrit aussi un préfixe nry_txn_live_ pour la production. Aucune clé de ce type ne peut être créée aujourd'hui : la production n'est pas ouverte (voir Limites du sandbox). Elle ne s'obtient par aucun geste : elle se demande, Noryo la revoit, et une approbation n'émet aucune clé de cette forme (voir Accès production).

Le préfixe fait partie de ce que le serveur vérifie : une clé présentée sous un préfixe qui ne correspond pas à celui enregistré à sa création est refusée 401, même si le secret est le bon.

Présenter la clé

La clé se transmet entière, préfixe compris, dans l'en-tête Authorization avec le schéma Bearer. C'est le seul schéma d'authentification du contrat.

curl -X POST https://api.noryo.app/transactions/v1/enrichments \
  -H "Authorization: Bearer $NORYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "descriptor": "PRLV SEPA NETFLIX INTERNATIONAL",
    "direction": "outgoing",
    "occurred_at": "2026-09-05T03:10:00+02:00",
    "amount": { "value": "13.49", "currency": "EUR" }
  }'

const response = await fetch("https://api.noryo.app/transactions/v1/enrichments", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.NORYO_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    descriptor: "PRLV SEPA NETFLIX INTERNATIONAL",
    direction: "outgoing",
    occurred_at: "2026-09-05T03:10:00+02:00",
    amount: { value: "13.49", currency: "EUR" },
  }),
});

Le contrat lui-même, GET https://api.noryo.app/openapi.json, est la seule ressource servie sans clé : une machine peut le lire sans contexte de workspace et sans consommer de débit.

Obtenir une clé sur Platform

Les clés se créent sur Platform, page « Clés d'API ». Vous vous y connectez avec votre identité Noryo ; les clés appartiennent au workspace dont vous êtes membre, pas à votre personne.

1. Activer le sandbox Transaction Intelligence. Un owner ou un admin du workspace l'active une fois ; l'activation est journalisée. Elle est propre à Transaction Intelligence, et elle demande un profil développeur complet pour le workspace : identité, téléphone professionnel, organisation, et ce que vous construisez. Sans lui, l'activation est refusée et aucune clé n'est émise.
2. Créer une clé. Vous lui donnez un nom et une intention. Platform rend alors la credential complète.
3. Copier le secret immédiatement. Il n'est montré qu'à ce moment. Noryo ne conserve pas le secret : seul un vérificateur en est gardé, qui permet de reconnaître la clé sans pouvoir la reconstituer. Un secret perdu ne se récupère pas ; on révoque la clé et on en crée une autre.

Le nombre de clés actives par workspace est plafonné. Platform lit ce plafond du serveur ; les clés révoquées n'y comptent pas.

Où garder le secret

Le secret est une credential de serveur. Il vit dans une variable d'environnement de votre serveur (NORYO_API_KEY dans les exemples de cette documentation), lue par le processus qui appelle l'API.

Un secret embarqué dans un client est lisible par quiconque tient ce client. Si une application mobile ou une page web a besoin d'enrichissements, faites-la passer par votre propre serveur, qui seul porte la clé.

Révocation

Une clé se révoque depuis Platform, immédiatement et sans délai de grâce. Dès la requête suivante, elle reçoit 401 ; cette requête n'est pas comptée dans l'usage et ne touche pas la limite de débit. La clé révoquée garde son historique dans la page Usage : ce qu'elle a fait avant la révocation reste lisible.

Des familles isolées

Noryo expose plusieurs API, chacune avec sa famille de clés. Une clé Merchant API, préfixée nry_mer_, est refusée 401 sur Transaction Intelligence, et une clé nry_txn_ est refusée sur l'API marchand. L'isolation tient au vérificateur lui-même, pas à un simple filtre sur le préfixe : une clé d'une autre famille est, pour ce serveur, une credential inconnue.

401 ou 403

Les deux refus liés à l'identité se lisent différemment.

Le 401 est volontairement unique : le serveur ne dit pas si la clé existe, si elle a existé, ou si seul le secret est faux. Distinguer ces cas offrirait un oracle d'énumération.

Ni le 401 ni le 403 ne consomment de jeton de débit, et aucun des deux n'apparaît dans l'usage sur Platform : la vérification de la credential précède le débit. Trois refus interviennent encore avant elle : 400 pour un hôte non déclaré, 415 pour un corps qui n'est pas du application/json, 413 pour un corps trop volumineux. Passé la credential, un 400 sur le JSON ou sur l'Idempotency-Key, un 422, un 404 ou un 409 consomme un jeton, parce que la clé était valide.

Un refus est un problème RFC 9457, en application/problem+json :

{
  "type": "https://noryo.app/problems/transactions/invalid_api_key",
  "title": "La credential presentee n'est pas utilisable.",
  "status": 401,
  "request_id": "req_01J9…"
}

Comparez le type, jamais le title : l'URI est stable, la phrase peut être reformulée. Le catalogue complet est dans Erreurs et sur /errors/invalid_api_key.

L'identifiant de requête

Toute réponse rendue après authentification porte l'en-tête noryo-request-id ; toute erreur, même antérieure à la credential, porte le même identifiant dans le champ request_id de son corps. C'est l'identifiant à citer au support.

Deux réponses viennent de l'hébergeur, avant l'API, et n'en portent pas : un 405 (verbe non déclaré sur un chemin connu, corps vide, sans en-tête Allow) et un 404 sur un chemin inconnu. Si votre appel reçoit l'un de ces deux codes sans noryo-request-id, vérifiez d'abord le verbe et le chemin.

Pour aller plus loin

• Quickstart : du premier accès Platform au premier enrichissement.
• Usage et clés d'API : ce que Platform montre par clé.
• Limites de débit : ce qui compte et ce qui ne compte pas.
• Erreurs et Référence : le catalogue et le contrat générés.