# 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.