API keys & authentication

Create keys, keep them safe, rotate them

API keys

Create a key

Open Dashboard → Developers → API keys and click Create key. Pick a name, a mode (Test or Live), and copy the secret. The secret is shown once — spuke stores only a SHA-256 hash. If you lose it, revoke and create a new one.

Keys look like:

sk_live_ABCDEfghi23jkLmnOPqrSTUv...   ← live
sk_test_ABCDEfghi23jkLmnOPqrSTUv...   ← test

Authenticate a request

Send the secret as a Bearer token in the Authorization header:

POST /v1/checkout/sessions HTTP/1.1
Host: api.spuke.com
Authorization: Bearer sk_test_ABCDEfghi23jkLmnOPqrSTUv...
Content-Type: application/json

Never call the API from the browser — the secret would leak to visitors. Always proxy through your own backend.

Scopes

Keys are unscoped by default and grant full merchant access (checkout:write, checkout:read, refunds:write, invoices:write). Per-scope keys are on the roadmap.

Rotation

Rotating a key is a two-step revoke:

  1. Create a new key, deploy it, verify traffic uses it.
  2. Revoke the old key in the dashboard (revoked_at is set immediately, all subsequent requests receive 401).

Idempotency

Every mutating request accepts an Idempotency-Key header. spuke stores the first response for 24 hours and returns the exact same status and body when the same key is sent again with the same payload. Reusing the key with a different payload returns 400 invalid_request (Idempotency-Key reused with different payload).

Idempotency-Key: order_9781_attempt_1