Every request to the SpherePay API must be authenticated using an API key. SpherePay uses Bearer token authentication — you pass your key in the Authorization header of every request. This page covers how to generate a key, how to use it, and how to handle authentication errors.
Obtain your API key
API keys are generated from the SpherePay dashboard:
- Log in to spherepay.co/dashboard.
- Navigate to Developers → API Keys.
- Select Create New API 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.
Make an authenticated request
Pass your API key as a Bearer token in the Authorization header on every request:
curl https://api.spherepay.co/v2/customer \
-H "Authorization: Bearer YOUR_API_KEY"
| Header | Required | Value |
|---|
Authorization | Yes | Bearer YOUR_API_KEY |
Content-Type | Yes for POST/PATCH | application/json |
Authentication errors
If your API key is missing, malformed, or invalid, the API returns a 403 Forbidden response:
{
"status": 403,
"detail": "Forbidden resource",
"correlationId": "e633f28100526862cadc4c592435eddd"
}
- The
Authorization header is formatted as Bearer YOUR_API_KEY with a single space between Bearer and the key — no extra characters or quotes.
- The key has not been revoked. Log in to the dashboard under Developers → API Keys to verify its status.
- You are sending the request over HTTPS, not HTTP.
