---
title: "API keys"
description: "Authenticate your API requests and keep your keys safe."
source: "https://docs.tokenz.one/en/v2/checkout/api-keys"
api_version: "v2"
locale: "en"
version_status: "current"
docs_stage: "prod"
---

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

```bash
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:

| Prefix | Mode | Moves money? |
| --- | --- | --- |
| `secret_test_…` | Test | No — simulated payments only |
| `secret_live_…` | Live | Yes — 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](https://docs.tokenz.one/en/v2/checkout/webhooks-get-started) for how to verify signatures.