# Keeping secrets safe

> Where a key's secret must live, what Noryo keeps of it and what it does not, what never appears in a response or a log, and what to do after a leak.

A Merchant API key is a bearer secret: whoever holds it calls the API on behalf of your workspace and, in Production, at your expense. This page describes what Noryo does with the secret and what is up to you.

## Where the secret must live

- **Server-side only.** Read the key from an environment variable or a secrets manager (`NORYO_API_KEY` in this documentation's examples).
- **Never in a client**: not in a JavaScript bundle served to a browser, not in a mobile app, not in a code repository, not in a ticket or a screenshot.
- **One key per use.** One key per service or per deployment can be revoked without cutting the others off. Give it only the scopes it needs: a service that only reads needs only `enrich:read`.

## What Noryo keeps, and what it does not

| Item | Kept by Noryo? |
|---|---|
| The secret | **No.** It is shown once, at creation, then no longer exists at Noryo |
| A verifier of the secret | Yes: an HMAC fingerprint computed with a server key that is not stored alongside the keys. A copy of the database is not enough to authenticate |
| The `key_id` and the prefix | Yes: they are not secret and are used to recognise a key |

As a result, Noryo cannot send you back a lost secret. It is replaced. See [Rotation](https://developer.noryo.app/en-GB/merchant/authentication/rotation).

## What never leaves

- **In responses**: no error body or header echoes the key presented, part of the secret or a fingerprint. The `WWW-Authenticate` header of a `401` is a fixed value.
- **In Noryo's logs**: the `Authorization` header, the secret, its verifier, the raw descriptor, the raw value of an `Idempotency-Key` and the `external_transaction_id` are never logged. To link two lines, Noryo logs truncated HMAC fingerprints, from which the value cannot be recovered.
- **In Platform**: the key list shows the prefix and the last four characters of the `key_id`, never the secret.

## Detecting a leak

The fixed prefix makes a key recognisable in a repository, a log or a secret-scanning tool. A pattern suited to keys issued by Noryo:

```text
nry_mer_(sbx|live)_[2-9A-HJKMNP-TV-Z]{10}\.[A-Za-z0-9_-]{43,}
```

Do the same in your own logs: never log the `Authorization` header, and mask any string matching this shape.

## After a leak

1. **Revoke the key** on the [API keys](https://platform.noryo.app/keys) page of Platform. It is refused with `401 invalid_api_key` from the next request. See [Revocation](https://developer.noryo.app/en-GB/merchant/authentication/revocation).
2. **Create a replacement key** with the same scopes and deploy it. See [Rotation](https://developer.noryo.app/en-GB/merchant/authentication/rotation).
3. **Check usage** on the [Usage](https://platform.noryo.app/usage) page: settled calls appear there with their `request_id`.

> **Warning** Revoking before the new key is deployed cuts your own traffic off. After a confirmed leak, revoke first anyway: a few minutes of `401` cost less than a key used by someone else.

---

Canonical page: https://developer.noryo.app/en-GB/merchant/authentication/secret-security