Skip to main content
API keys authenticate your server-to-server calls to the /api/v1/* endpoints. Every request to the public API must include a valid key in the Authorization header. Keys are scoped to specific resources and can be created in either live or test mode, giving you full control over what each integration can access.

​
Key format

Keys follow a fixed prefix convention so you can identify them at a glance:
PrefixMode
ck_live_Live mode — real payments, real funds
ck_test_Test mode — development and staging
After the prefix, keys contain 32 base-62 characters of cryptographic randomness. Keys are hashed with SHA-256 before storage, so the raw value is never written to the database.

​
Creating a key

1

Open Dashboard → API Keys

Click API Keys in the left sidebar. The page lists all existing keys with their prefix, scopes, mode, last-used timestamp, and status.
2

Click New Key

Click the New Key button in the top-right corner of the page.
3

Name the key and choose a mode

Give the key a descriptive name (for example, Production server or WooCommerce plugin). Select Live for production use or Test for development and staging environments.
4

Select scopes

Choose the minimum set of scopes your integration needs. See the scopes table below for a full list of what each scope grants.
5

Copy the raw key immediately

After creation, the dashboard shows the full raw key once. Copy it now — it cannot be retrieved again. Only the short prefix (e.g. ck_live_abc123) is stored and displayed in the key list after this point.
If you lose the raw key before copying it, revoke it and create a new one. There is no way to recover a key after the creation dialog is closed.

​
Available scopes

ScopeAccess
links:readList and retrieve payment links
links:writeCreate, update, and delete payment links
sessions:readList and retrieve checkout sessions
sessions:writeCreate checkout sessions
webhooks:readList and retrieve webhook endpoints
webhooks:writeCreate and delete webhook endpoints
events:readList and retrieve events
customers:readList and retrieve customers
customers:writeCreate and update customers
Grant only the scopes your integration actually uses. A key used solely to create sessions, for example, needs only sessions:write — there’s no reason to add links:write or webhooks:write.

​
Using a key

Include the raw key as a Bearer token in every request: 
Authorization: Bearer ck_test_YOUR_KEY_HERE
Example with curl: 
curl https://checkout.example.com/api/v1/sessions \
  -H "Authorization: Bearer ck_test_YOUR_KEY_HERE" \
  -H "Content-Type: application/json"
Example with the TypeScript SDK: 
import { CheckoutClient } from "@your-org/checkout-sdk";

const client = new CheckoutClient({
  apiKey: process.env.CHECKOUT_API_KEY!,
  baseUrl: "https://checkout.example.com",
});

const session = await client.checkoutSessions.create({
  amount: { value: "49.99", currency: "USD" },
  successUrl: "https://your-store.com/thank-you",
  metadata: { orderId: "order_789" },
});

​
Revoking a key

To revoke a key, find it in the API Keys list and click Revoke. Revocation is immediate — any subsequent request using that key will receive a 401 Unauthorized response. Revoked keys remain visible in the list with a revoked timestamp for audit purposes but cannot be reinstated.

​
Key list details

The API Keys page shows the following for each key:
ColumnDescription
NameThe label you assigned at creation
PrefixThe first several characters of the key (e.g. ck_live_abc123) for identification
ModeLive or test
ScopesThe permissions assigned to this key
Last usedTimestamp of the most recent successful authentication
CreatedWhen the key was generated
StatusActive or revoked

​
Best practices

Following these practices limits the blast radius of a leaked key and makes it easier to rotate credentials without downtime.
  • One key per integration. Create a separate key for your WooCommerce plugin, your backend server, and any other consumer. This lets you revoke a single integration without affecting others.
  • Use test keys during development. Switch to a ck_test_ key in your staging and local environments so accidental misfires never touch real payments.
  • Apply minimal scopes. Request only the scopes each integration needs. A webhook consumer only needs webhooks:read; a session creator only needs sessions:write.
  • Rotate keys periodically. Create a new key, update your integration, then revoke the old key. Both keys can coexist briefly during the cutover.
  • Never expose keys client-side. API keys are for server-to-server use only. Do not embed them in browser JavaScript, mobile apps, or public repositories.