Authentication

Coal uses two authentication models depending on what you are trying to do:

• Merchant API keys for server-to-server access
• Privy Bearer tokens for dashboard and console requests

Merchant API requests use x-api-key with coal_live_* keys. /api/console/* routes are dashboard-only and should not be treated as the primary public merchant surface.

The API playground supports both.

Merchant API Keys

For backend integrations, use a Coal API key. Keys are created in the Console, shown once at creation time, and stored server-side only as a hash.

Key format

1coal_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0

How to send it

Merchant API requests use the x-api-key header:

1curl https://api.usecoal.xyz/api/checkouts \
2  -H "x-api-key: coal_live_your_key_here" \
3  -H "Content-Type: application/json"

Node.js example

1const res = await fetch('https://api.usecoal.xyz/api/checkouts', {
2  method: 'POST',
3  headers: {
4    'x-api-key': process.env.COAL_API_KEY!,
5    'Content-Type': 'application/json',
6  },
7  body: JSON.stringify({
8    amount: 49.99,
9    currency: 'USDC',
10    productName: 'Pro Plan',
11  }),
12});

Python example

1import os
2import requests
3
4response = requests.post(
5    "https://api.usecoal.xyz/api/checkouts",
6    headers={
7        "x-api-key": os.environ["COAL_API_KEY"],
8        "Content-Type": "application/json",
9    },
10    json={
11        "amount": 49.99,
12        "currency": "USDC",
13        "productName": "Pro Plan",
14    },
15)
16response.raise_for_status()

Privy Bearer Tokens

Coal's dashboard and console APIs are authenticated with Privy. When a user signs in through the browser, Privy issues a Bearer token that Coal sends automatically for console requests.

Example:

1curl https://api.usecoal.xyz/api/console/settings \
2  -H "Authorization: Bearer <Privy JWT>"

This token is handled automatically by the Coal frontend. Most integrations should not need to manage it directly.

Which auth model should I use?

Security Best Practices

Store keys in environment variables and keep them server-side.

1COAL_API_KEY=coal_live_your_key_here

Do not use merchant API keys as console Bearer tokens. They are different mechanisms for different endpoint families.

Rotate keys deliberately and revoke any key immediately if you suspect leakage.

Common Errors

Playground Tip

Use the API playground from the docs sidebar when you want live request and response testing with persisted auth state.