A key carries an explicit set of scopes. There is no key tier and no implicit inheritance: a scope you did not tick is a scope the key does not have.

​
The three grants

For any resource family, such as products: Three separate grants, 136 scopes in total across 66 resource families.
Write does not imply read. A key with only write_products cannot list your catalogue. If your integration reads a record before updating it, which most do, you need both.

​
Why delete is split out

Deleting is the only irreversible operation in the set, so it is the one worth granting separately. The common case is an integration that keeps records in sync: it creates and updates constantly and should never destroy anything. Under a two-grant model, giving it write also gives it the ability to wipe your catalogue if it has a bug or its credentials leak. Splitting delete out means that blast radius is something you opt into explicitly. Grant :delete only when the integration genuinely needs to remove records.

​
Picking the minimum

1

List the endpoints your integration actually calls

Work from your code, not from what you might need later. Scopes can be added to an existing key at any time without reissuing it.
2

Map each to its family and verb

GET /products needs read_products. POST /orders needs write_orders.
3

Leave delete off unless you delete

This is the single highest value restriction available to you.
4

Let the API tell you what you missed

A refusal names the exact scope required, so you can develop against a minimal key and add scopes as you hit them rather than guessing up front.

​
Being refused

A valid key on a route it lacks the scope for returns 403:
The message names the scope. Add it to the key in Settings, API keys and retry. You do not need a new key, and existing traffic on that key is unaffected.
403 insufficient_scope means the key is real and the permission is missing. 401 unauthorized means the credential itself did not check out. They are different problems: one is fixed in the dashboard, the other in your secret store.

​
Reading the scope list on a key

The dashboard shows the current scope set for each key. Reviewing this periodically is worth doing, because scopes accumulate: a scope added during a debugging session tends to stay ticked long after the reason for it is gone.

​
Scopes and tenancy are different things

Scopes control which operations a key may perform. They do not widen what data it can reach. A key is bound to your store, and no scope grants access to another merchant’s records. Tenant isolation is enforced in the database rather than in the handler, so it does not depend on any route remembering to filter.