Keys and permissions
Every request carries a key, sent as Authorization: Bearer <key>. Keys are created in Usual → Developers by someone in the store's admin, and belong to that one store.
API keys and agent keys
| API key | Agent key | |
|---|---|---|
| For | Your code and integrations | AI agents |
| Changes | Applied directly, unless they need approval | Always a plan first |
| Must say why | No (but you can, with X-Change-Reason) | Yes |
| Needs approval for | Financial changes | Medium risk and up, or more than 25 records |
Use an agent key for anything an AI drives, even through the REST API. It's what tells Usual to be careful.
Permissions
Give each key only what it needs. A key without a permission gets 403 forbidden with the missing permission named.
| Permission | Allows |
|---|---|
settings:read | Read store settings |
settings:write | Change store settings |
audit:read | Read the activity log and plans |
subscriptions:read | Read subscriptions |
subscriptions:write | Skip, reschedule, pause, resume and cancel subscriptions |
subscriptions:sync | Re-check subscriptions against Shopify |
offers:read | Read subscription offers |
offers:write | Create and change subscription offers |
billing:read | Read charges, retries and billing health |
billing:write | Retry failed charges (always needs approval for keys and agents) |
imports:read | Read subscription imports from other apps |
imports:write | Import subscriptions from another app and start billing them |
integrations:write | Connect and disconnect Klaviyo |
Some things only a person in the admin can do, whatever the key: creating and revoking keys, and approving plans. Agent keys also can't connect another app's account (Recharge, Klaviyo): their changes are saved as plans first, and a plan would have to keep the other app's secret.
Keeping keys safe
- Keys are shown once when created. We store only a hash.
- Revoke a key from the Developers page and it stops working immediately.
- Each key shows when it was last used.
- Never put a key in a web page or app that customers can see.