Authentication

API keys#

Every call from your server sends an API key:

HTTP

Authorization: Bearer cv2_<mode>_<prefix>_<secret>

Create keys in the dashboard under API Keys, as Live or Test (see Live and Test mode). A key is shown once, at creation; rotating it keeps its mode. A missing, invalid or revoked key is answered 401 UNAUTHORIZED. A valid key on a deactivated or suspended account is answered 403 (ACCOUNT_DEACTIVATED / ACCOUNT_NOT_ACTIVE).

Never put an API key in a browser, a mobile app or a git repository. Keep it in your server's environment.

Scopes#

Each key carries scopes that limit what it can do. A key without the scope a route needs gets 403 INSUFFICIENT_SCOPE — the key is fine, it needs another scope.

Scope	Allows
`invoices:write`	Create, switch and cancel invoices
`invoices:read`	List and read invoices and their payments
`webhooks:write`	Create, update and delete webhooks; rotate their secrets; retry a delivery
`webhooks:read`	List webhooks and their delivery log
`balances:read`	Read address balances and your prepaid credit balance
`customers:write`	Create, update and delete customers
`customers:read`	List and read customers and their addresses
`subscriptions:write`	Create, change and delete plans; create and change subscriptions; activate, cancel, apply credit
`subscriptions:read`	List and read plans, subscriptions and their events

Give each service its own key with only the scopes it needs — a webhook manager does not need invoices:write.

Plan limits#

Your plan sets how many API keys, webhooks and checkout buttons the account can hold:

Plan	API keys	Webhooks	Checkout buttons
Free	1	1	1
Starter	10	10	100
Growth	25	25	500
Business	50	50	2,000
Scale	100	100	10,000

One more than your plan allows is refused 409 ACCOUNT_RESOURCE_LIMIT_REACHED. Revoke or delete one, or upgrade.

Idempotency#

POST /invoices requires an Idempotency-Key header; POST /customers and POST /subscriptions accept one. Use one key per order, such as your own order id:

The same key with the same body within 24 hours returns what was already created, with status 200 — nothing is created twice, even when retries arrive at the same instant.
The same key with a different body, or on another endpoint, is refused 409 IDEMPOTENCY_KEY_REUSED.
While the first request is still being processed, a repeat is answered 409 IDEMPOTENCY_KEY_IN_PROGRESS with a Retry-After header. Retry after it to receive the result.
Only a successful creation is remembered: after an error you can retry with the same key. After 24 hours the key is free again.
A key can be at most 255 characters. A longer one is refused 400 IDEMPOTENCY_KEY_TOO_LONG ("Idempotency-Key is 300 characters long; it can be at most 255…") and nothing is created.