Loading search…

Loading search…

Skip to content
Checkout integrationAPI keys

API keys

Authenticate your API requests and keep your keys safe.

Introduction

Every request to the Tokenz API v3 is authenticated with a secret API key, sent as a bearer token:

bash
curl https://api.tokenz.one/v3/checkoutsession \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE'

Tokenz API v3 uses secret keys only — there is no publishable or client-side key. A secret key can create charges and read order data on your account, so it must never leave your server.

You create and manage keys in the dashboard under Developers → API keys.

Test and live keys

Each key belongs to one mode:

Scroll horizontally if needed
PrefixModeMoves money?
secret_test_…TestNo — simulated payments only
secret_live_…LiveYes — real payments

Build and test your integration with a test key, then switch to a live key for production. A test key cannot process real payments, and a live key cannot be used in test mode — so keep them in separate environment configurations (for example, a TOKENZ_SECRET_KEY variable that differs per environment).

Keep your secret key secret

Because there is no client-safe key, treat the secret key like a password:

  • Server-side only. Never put it in browser code, a mobile app, a single-page-app bundle, or anything shipped to a user's device.
  • Never commit it to source control, and keep it out of logs, error messages, and URLs.
  • Store it in an environment variable or a secrets manager — not in your codebase.

A key is shown once, when you create it. Copy it then and store it securely. If you lose it, create a new key rather than trying to recover the old one.

Grant only the scopes a key needs

When you create a key you choose its permissions (scopes) — for example checkout-session create/read, order read/cancel, delivery record, product read, refund create/read, redemption-code validate/redeem, or subscription plan changes.

Give each key the least privilege it needs:

  • Use a separate key per integration or service, with only the scopes that integration uses. A reporting job that only reads orders doesn't need refund or checkout permissions.
  • If a narrowly-scoped key leaks, the blast radius is small and you can revoke just that key without disrupting everything else.

Rotate and revoke keys

  • Rotate by creating a new key, deploying it, and then deleting the old one under Developers → API keys. Because you can hold several keys at once, you can roll without downtime.
  • If a key is ever exposed — committed to a repo, pasted in a ticket, logged — delete it immediately. Deleting a key revokes it, and any request using it stops working. Then issue a replacement.

Webhook signing secrets

A webhook endpoint's signing secret is separate from your API keys. Tokenz signs each webhook with it, and you verify the Tokenz-Signature header against the raw request body to confirm the event is genuine. Keep the signing secret server-side, the same as your API keys.

See Webhooks for how to verify signatures.