# API keys

> The anatomy of a Merchant API key, creating one in Platform, the secret shown only once, scopes, and what several keys of one workspace share.

A Merchant API key is a single string that carries its environment, a public identifier and a secret. It belongs to a workspace and carries scopes.

## Anatomy

```text
nry_mer_sbx_7XKD2M9QPA.<secret>
└──────────┘└────────┘ └──────┘
   prefix     key_id     secret
```

| Part | Role | Secret? |
|---|---|---|
| `nry_mer_sbx_` or `nry_mer_live_` | API family and environment | no |
| `key_id` | Public identifier of the key: 10 characters from `23456789ABCDEFGHJKMNPQRSTVWXYZ`, upper case only | no |
| secret | 32 random bytes encoded as Base64URL without padding, i.e. 43 characters | **yes** |

The `key_id` alphabet excludes ambiguous characters (`0`, `O`, `1`, `I`, `L`, `U`): a key copied by hand cannot silently become a different key. Case is never corrected: a lower-case `key_id` is refused. The `key_id` above illustrates the shape; it is not a real key.

## Creating a key

Sandbox keys are created on the [API keys](https://platform.noryo.app/keys) page of Platform.

1. Sign in to Platform with your Noryo identity and choose your workspace.
2. Give the key a name (for example `test integration`).
3. Tick the scopes: `enrich:read`, `enrich:write`, or both (both by default).
4. Create the key, then **copy the secret immediately**.

> **Important** The secret is shown once, at creation, and is never recoverable. Noryo does not store it: only a verifier derived from the secret is kept. A lost secret is replaced, not recovered. See [Rotation](https://developer.noryo.app/en-GB/merchant/authentication/rotation).

Until Noryo has opened Sandbox key issuance, the server refuses creation with the message `Sandbox access is not enabled yet.`. Platform only issues Sandbox keys: it offers no way to create a Production key, which can only exist once your application is approved. See [Going live](https://developer.noryo.app/en-GB/merchant/going-live).

Any member of the organisation can create and revoke the keys of its workspaces.

## The key list

The same page lists the workspace's keys:

| Column | Content |
|---|---|
| name | The name given at creation |
| `key_id` | The public identifier |
| key | The prefix followed by the last four characters of the `key_id` (`nry_mer_sbx_…9QPA`) |
| scopes | `enrich:read`, `enrich:write` |
| created, last used | Creation and last-use dates |
| state | `active` or revoked |

The secret never appears there: it exists nowhere at Noryo.

## Scopes

| Scope | Allows |
|---|---|
| `enrich:read` | Reading a result back (`GET`) |
| `enrich:write` | Creating an enrichment and refreshing it (`POST`) |

A key that only writes does not need `enrich:read`, and the other way round. A route called without its scope returns `403 insufficient_scope`.

## Several keys in one workspace

| Shared by the keys of a workspace (per environment) | Specific to each key |
|---|---|
| Results: any key of the workspace and the same environment can read an `enrichment_id`, whichever key created it | The rate-limit bucket |
| The `Idempotency-Key` space | The scopes |
| Deduplication by `external_transaction_id` | Revocation |

In practice: two services sharing a workspace also share the idempotency key space. Prefix your `Idempotency-Key` values per service, or generate them uniquely. See [Idempotency](https://developer.noryo.app/en-GB/merchant/requests/idempotency).

---

Canonical page: https://developer.noryo.app/en-GB/merchant/authentication/api-keys