Skip to main content
Every request is sent from your server with a secret key in the Authorization header:
Create keys in the dashboard under Developers → API Keys.

​
Kinds of key

Secret and restricted keys can move money. Keep them on your server, in environment variables or a secrets manager. Never put them in a browser, a mobile app or a git repository.

​
Restricted keys

A restricted key only reaches what you allow. Give each service the smallest set it needs: a usage collector only needs usage:write, a paywall only needs entitlements:read. A scope is {resource}:{access}, such as customers:read or refunds:write. Write access includes read. GET requests need read access and everything else needs write. A request outside the key’s scopes gets 403 permission_denied naming the missing scope, and its Idempotency-Key is not used up. POST /subscriptions/{id}/items/{item}/preview and POST /subscriptions/{id}/plan-change/preview only need subscriptions:read, since they change nothing.

​
Test and live keys

A key’s mode decides which gateway connection it charges through and which saved cards it can see. A test key can never charge a live card. See Going live.