Authentication

Every request needs an API key in the Authorization header:

Authorization: Bearer sc_key_9fK2...x7Qa

A key stands for your account. Anything sent with it goes to your agent, lands in your chats and uses your credits.

#Create a key

Keys live in the API dashboard (Dashboard → API).

1. Click Create key and give it a nickname that says where it's used: "Zapier", "prod server", "Sam's laptop".
2. Optionally set it to expire after 30, 90 or 365 days. The default is never.
3. Copy the key. It's shown once. SuperCool stores only a hash of it, so it can't be shown again.

The dashboard lists each key by nickname with its first and last characters (sc_key_9fK2…x7Qa), when it was created and last used, and its requests and credits over the last 30 days. You can rename a key at any time. An account can have up to 20 active keys.

#Keep keys on your server

API keys are secrets, like a password to your account.

• Never put a key in a web page, mobile app or public repo. The API sends no CORS headers, so browsers refuse to call it from a web page. That's deliberate: a key in front-end code is a key anyone can copy.
• Load keys from an environment variable or a secret manager, not from source code.
• Use one key per integration. Then the dashboard shows usage per integration, and you can revoke one without touching the others.

To call SuperCool from a front end, send the request to your own backend and have your backend call the API.

#Check a key

GET /v1/me returns the account a key belongs to, your plan, available credits, your agent's name, the key's id and nickname, and your limits:

curl https://api.supercool.com/v1/me -H "Authorization: Bearer $SUPERCOOL_API_KEY"

{
  "object": "account",
  "user_id": "64f1c2a9e4b0a1b2c3d4e5f6",
  "email": "[email protected]",
  "name": "Sam Rivera",
  "plan": "pro",
  "credits": 1840,
  "agent": { "name": "Nova" },
  "key": { "id": "pat:6a1b2c3d4e5f", "name": "prod server" },
  "limits": { "running_jobs": 5, "requests_per_minute": 600 }
}

#Rotate a key

To replace a key without downtime:

1. Create a new key in the dashboard.
2. Deploy it everywhere the old one is used.
3. Watch the old key's last used time in the dashboard. Once it stops moving, revoke it.

Idempotency keys are scoped to the API key that sent them. A retry sent with the new API key is treated as a new request, so finish or abandon in-flight retries before you switch.

#Revoke a key

Revoke a key from the dashboard. It stops working on the next request. Messages and work it started keep running and stay in your account and in the app, but that key can no longer read them.

If a key leaks, revoke it right away and create a new one. Your request inspector in the dashboard shows every request each key made in the last 30 days, with its IP country.

#Authentication errors

A missing, unknown, expired or revoked key gets 401 with the error code unauthorized and a WWW-Authenticate: Bearer header:

{
  "error": "unauthorized",
  "message": "unknown or revoked token. Send your API key as 'Authorization: Bearer sc_key_…'.",
  "request_id": "req_6c2f0e1d9a8b7c6d5e4f3a2b",
  "docs": "https://supercool.com/docs/api/errors#unauthorized"
}

The SuperCool CLI's sign-in token also works as a bearer token on /v1, but for servers and scripts, use an API key.