Authentication and API keys

Every API request carries your secret key in the Authorization header:

curl https://pwn-api.142-93-42-70.sslip.io/v1/whoami \
  -H "Authorization: Bearer sk_test_your_key_here"

Your keys

You have a pair of keys for each mode.

Key	Looks like	Where it goes	What it can do
Secret	sk_test_…, sk_live_…	Your server only	Everything in the API reference
Publishable	pk_test_…, pk_live_…	Your web page or app	Start and open the inline checkout

Keys are long and random: the prefix, then 43 letters and digits.

The mode comes from the key. A sk_test_ key only sees test payments, test customers and test webhook endpoints, and moves no money. A sk_live_ key only sees live ones. The two never mix, and there is no mode parameter to change it.

Keep the secret key secret

Never put a secret key in a web page, a mobile app, a public repository or a support message. Anyone who has it can act as your business. Keep it in an environment variable or a secrets manager on your server. If it leaks, roll it at once.

A publishable key is meant to be seen: it sits in your page’s HTML. It can do one thing: start a checkout (POST /v1/checkout/initialize, which the inline checkout script calls for you). Every other endpoint refuses it (403 SECRET_KEY_REQUIRED), so a leaked publishable key cannot read or change anything. That one endpoint refuses a secret key in turn (403 PUBLISHABLE_KEY_REQUIRED): a secret key must never be in a web page.

Getting keys

• Test keys are issued when you sign up and shown once on the next screen.
• Live keys become available when your business is verified (see Going live). Under Developers → API keys → Live keys, issue your live secret key, and create your live public key if you use the inline checkout.

Owners, admins and developers on your team can see and roll keys. We keep only a fingerprint of a secret key, so it is shown once, when it is issued, and never again. A publishable key stays visible in the dashboard.

Rolling a key

Roll a key when it may have leaked, when someone who knew it leaves, or on a schedule. Open Developers → API keys and press Roll next to the key, then choose what happens to the current key:

• Stops working now: the right choice if the key may have leaked. Requests with it fail from that moment.
• Keeps working for 1 hour, 24 hours, 3 days or 7 days: for a planned rotation. Both keys work, so you can deploy the new one to every server at your own pace. The old key shows as Previous key, with when it stops; press Stop it now once nothing uses it any more, or let it run out.

At most two keys of a kind work at once: rolling again stops a key that is still in its overlap. A secret key is shown once, when it is issued, so copy it straight away. When a key has stopped, requests with it get 401 INVALID_API_KEY (“…has been revoked…” or “…expired after it was rolled…”).

Rolling a test key never affects live, and the other way round.

When a key is refused

Status	error.code	Why	What to do
401	UNAUTHENTICATED	No Authorization: Bearer … header.	Send the header. The scheme is Bearer, then a space, then the key.
401	INVALID_API_KEY	The key is unknown, mistyped or revoked.	Copy the key again, or roll it.
403	SECRET_KEY_REQUIRED	You sent a publishable key (pk_…).	Use the secret key, from your server.
403	PUBLISHABLE_KEY_REQUIRED	You sent a secret key to POST /v1/checkout/initialize, the browser’s endpoint.	Use your publishable key in the page, and roll the secret key if it was ever in one.
403	LIVE_MODE_NOT_ENABLED	A live key, before your business is verified.	Use test keys until then.
403	ACCOUNT_RESTRICTED	The account is suspended.	Contact us.

Checking a key

GET /v1/whoami tells you which business and mode a key acts for. It is a cheap health check for your integration:

{
  "data": {
    "merchant_id": "mer_01M3XX8A3AF4TAM85PZC0B4821",
    "business_name": "Baraka Foods",
    "mode": "test",
    "key": { "id": "key_01M3XX8A3DFRSVJ2HEYZB8QPD1", "kind": "secret", "last4": "VrJj" }
  },
  "meta": { "request_id": "01a0fbd4-3b05-7281-9e2b-88f10fd7f0f0" }
}

The dashboard is separate

The dashboard signs people in with a password and uses its own short-lived session tokens. Those are not API keys, and the dashboard’s own endpoints (team, settings, business verification) are not part of this API. Your integration only ever needs the secret key.