# Authentification

> Comment présenter une clé d'API Transaction Intelligence, où garder son secret, et ce que signifient les réponses 401 et 403.

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](https://developer.noryo.app/fr-FR/transaction-intelligence/quickstart) ; la lecture de l'usage par clé dans [Usage et clés d'API](https://developer.noryo.app/fr-FR/transaction-intelligence/usage-and-api-keys).

## 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](https://developer.noryo.app/fr-FR/transaction-intelligence/sandbox-limitations)). 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](https://developer.noryo.app/fr-FR/transaction-intelligence/production-access)).

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.

```bash
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" }
  }'
```

```ts
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](https://platform.noryo.app/keys), 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.

> **Note** Il n'existe pas de procédure de rotation documentée. Pour remplacer une clé : révoquez-la, puis créez-en une nouvelle. Si vous soupçonnez qu'un secret a fuité, révoquez d'abord.

## 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.

| Emplacement | Verdict |
|---|---|
| Variable d'environnement d'un serveur, ou gestionnaire de secrets | Recommandé |
| Bundle JavaScript servi au navigateur | Jamais |
| Dépôt de code public, ou fichier commité | Jamais |
| Binaire d'une application mobile | Jamais |
| JavaScript côté client, extension, page web | Jamais |

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](https://platform.noryo.app/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.

| Statut | `type` du problème | Ce que cela signifie | Que faire |
|---|---|---|---|
| `401` | `invalid_api_key` | La credential n'est pas utilisable : absente, mal formée, d'une autre famille, inconnue, révoquée, ou présentée sous un préfixe qui ne correspond pas. | Vérifiez l'en-tête `Authorization`, puis l'état de la clé sur Platform. |
| `403` | `account_inactive` | La clé est reconnue, mais le workspace ou l'organisation n'est pas actif. | Contactez le support avec le `request_id`. |

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` :

```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](https://developer.noryo.app/fr-FR/transaction-intelligence/errors) et sur [/errors/invalid_api_key](https://developer.noryo.app/fr-FR/transaction-intelligence/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.

> **Attention** Ne mettez jamais la clé dans un ticket de support, un journal applicatif ou une capture d'écran. Le `noryo-request-id` suffit.

## Pour aller plus loin

- [Quickstart](https://developer.noryo.app/fr-FR/transaction-intelligence/quickstart) : du premier accès Platform au premier enrichissement.
- [Usage et clés d'API](https://developer.noryo.app/fr-FR/transaction-intelligence/usage-and-api-keys) : ce que Platform montre par clé.
- [Limites de débit](https://developer.noryo.app/fr-FR/transaction-intelligence/rate-limits) : ce qui compte et ce qui ne compte pas.
- [Erreurs](https://developer.noryo.app/fr-FR/transaction-intelligence/errors) et [Référence](https://developer.noryo.app/fr-FR/transaction-intelligence/reference) : le catalogue et le contrat générés.

---

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