API keys
Every request carries a key as a bearer token: Authorization: Bearer sticky_live_…. Keys are created under Developers → API keys in the admin, shown once, and stored hashed. A key belongs to one programme and one mode:
sticky_test_…writes to the programme's sandbox — see Test mode.sticky_live_…writes to the real programme.
Keys issued before the rename (cvos_live_…, cvos_test_…) keep working forever.
Scopes
A key carries one or more of four scopes. Give each integration the least it needs.
| Scope | Lets the key… |
|---|---|
ingest | Send events, and read back the status of the events it sent. |
read | Read members, ledgers, redemptions, the programme, liability; mint member session tokens; ask for redemption quotes. |
act | Enrol, update and erase members; adjust balances; reserve, redeem, confirm, void; apply referrals; mint portal links. |
webhooks | Manage webhook endpoints. |
Every operation in the reference states its scope as x-required-scope. A key without it gets 403 forbidden with the missing scope in detail.
Which key for what
| You are building… | Scopes |
|---|---|
| A store that sends orders and shows balances | ingest, read |
| …that also redeems at checkout or enrols customers | add act |
| A till that issues and confirms vouchers | read, act |
| A reporting sync | read |
| A webhook receiver's configuration script | webhooks |
Rotation and revocation
Rotate mints a new key with the same scopes; the old one keeps working for 24 hours so you can deploy the new one first. Revoke stops a key immediately, with no grace — use it for a leaked key.
Test vs live in one integration
Read the mode from GET /v1/ping (data.mode) rather than parsing the prefix, and never let a test key's data reach live code paths: the sandbox is a separate programme with its own members.
Member session tokens are not API keys
A browser or app never holds an API key. Your server mints a member session token (POST /v1/members/{id}/session-tokens, scope read) — read-only, one member, 15 minutes — and the page uses it against GET /v1/public/member only. See A mobile app.