Authentication
Send your API key as a bearer token; test and live keys, rolling and limits.
Every request to /api/v1 carries your application's API key as a bearer token:
curl -s "$BRIDGE_URL/api/v1/payments/01a13c8c-8592-70f4-9ef9-d3767e74d54c" \
-H "Authorization: Bearer pk_test_a1B2c3D4e5F6_..." \
-H "Accept: application/json"
Send the whole key exactly as it was shown to you. Requests and responses are JSON; send
Content-Type: application/json with a body and Accept: application/json on every request.
Call the API only from your server. An API key in a browser or a mobile app can be copied by anyone who uses it.
Test and live keys
| Key | Starts with | Payments go to |
|---|---|---|
| Test | pk_test_ |
The built-in simulator. No real money. |
| Live | pk_live_ |
The provider account linked to your application. Real money. |
The key decides the mode of everything you do with it. A payment created with a test key is a test payment, and only test keys can fetch, cancel or refund it; the same goes for live.
Getting and rolling keys
- Your application's Owner creates keys in the application dashboard, under API keys. Alphabet staff can also issue keys for your application.
- A key is shown once, when it is created. Afterwards the dashboard shows only its start and
its last four characters, for example
pk_test_a1B2c3D4e5F6_…wxyz. If you lose a key, create a new one. - Rolling a key creates a new one and revokes the old one immediately. Update your servers
with the new key before you roll, or expect
401responses until you do. - A revoked key answers
401 invalid_api_key.
When a key is refused
| HTTP | error.code |
Meaning |
|---|---|---|
| 401 | unauthenticated |
No Authorization: Bearer … header. |
| 401 | invalid_api_key |
The key is unknown, revoked or rolled. |
| 403 | application_disabled |
The application is switched off. Contact Alphabet. |
| 403 | application_pending_review |
Alphabet has not activated the application yet. |
| 403 | application_suspended |
Alphabet has suspended the application. |
| 403 | ip_not_allowed |
Your application has an IP allow-list and this request came from another address. |
The full list is on Errors.
IP allow-list
Alphabet can restrict your application's keys to a list of server IP addresses or ranges. When a
list is set, requests from any other address answer 403 ip_not_allowed. Ask Alphabet to add
an address before you move your servers.
Rate limit
Each key may make 120 requests per minute. Over that, the API answers 429 rate_limited with a
Retry-After header giving the seconds to wait.
Webhook signing secret
Webhooks are signed with a separate secret that starts with whsec_. It is not an API key and is
never sent in a request. See Webhooks.