API keys

Authenticate your API requests and keep your keys safe.

Introduction

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

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

Tokenz 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:

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.