Choose API key scopes

Overview

• Current public scopes are catalogue:read/write, stores:read/write, orders:read/write, payments:read/write, customers:read/write, loyalty:read/write, gift_cards:read/write, vouchers:read/write, and reports:read.
• New keys default to a deliberately limited read-only set: catalogue:read, stores:read, orders:read, and customers:read.
• An API-key request that lacks the exact scope required by a public endpoint receives 403 Forbidden.
• Read scope does not imply Write scope and Write scope should not be granted unless the integration actually changes data.

When to use this

• Design scopes separately for each integration according to what it must read or mutate.

Step-by-step

1. List the endpoint groups the integration needs.
2. Start with Read scopes.
3. Add a Write scope only for required mutations.
4. Test a denied operation to verify least privilege.
5. Create a new narrower/replacement key if requirements change substantially.

Common mistakes

• Do not grant every scope to avoid thinking about permissions.
• Do not assume reports:read gives access to raw Orders/Payments endpoints.
• Do not expect a scope to override Business tenancy; keys remain confined to their Business.

Troubleshooting

• A 403 naming a required scope means authentication succeeded but the key lacks permission.
• A 401 indicates missing/invalid/inactive/expired credentials rather than a scope mismatch.