Authentication

All requests to the SpherePay API must be authenticated using an API key. SpherePay uses Bearer token authentication — your API key is passed in the Authorization header of every request.

Obtaining your API key

API keys are generated from the SpherePay Dashboard:

Log in to spherepay.co/dashboard.
Navigate to Settings → API Keys.
Click Generate New Key.
Copy the key immediately — it will not be shown again after you leave the page.

Treat your API key like a password. Never expose it in client-side code, commit it to version control, or share it in plaintext. If a key is compromised, revoke it immediately from the Dashboard and generate a new one.

Making an authenticated request

Pass your API key as a Bearer token in the Authorization header:

curl https://api.spherepay.co/v2/customer \
  -H "Authorization: Bearer YOUR_API_KEY"

All requests must also use HTTPS. Requests made over plain HTTP will be rejected.

Request headers

Header	Required	Value
`Authorization`	Yes	`Bearer YOUR_API_KEY`
`Content-Type`	Yes for POST/PATCH	`application/json`
`Idempotency-Key`	Recommended for POST	A unique UUID per request

Key types

SpherePay issues API keys for production use:

Type	Prefix	Purpose
Live key	`sk_live_`	Used in your production environment for real transactions.

Authentication errors

If your API key is missing, malformed, or invalid, the API will return a 401 Unauthorized response:

{
  "status": 401,
  "detail": "Invalid or missing API key.",
  "code": "unauthorized"
}

If you receive this error on a key you believe is valid, verify that:

The Authorization header is formatted as Bearer YOUR_API_KEY with a space between Bearer and the key.
The key has not been revoked in the Dashboard.