Get started

Authentication

Every request to the API carries an API key. A key belongs to one workspace, and you can create as many as you need and revoke any of them at any time.

Two kinds of key

Key	Looks like	What it can do
Workspace key	`ck_…`	Everything in its workspace: create and edit agents and tools, start and manage calls, read call logs and balance, manage webhooks.
Agent key	`gs_agent_…`	Start, read, speak into and end calls for one agent. Nothing else.

Use a workspace key for your backend. Use an agent key where less access is enough, for example a service whose only job is to start calls with one agent: with it, agentId can be left out of POST /v1/calls. Each page of the API reference says which keys the request accepts.

Sending a key

Send the key as a bearer token:

Header

Authorization: Bearer ck_your_key_here

X-API-Key: ck_your_key_here is accepted in its place. The samples in these docs read the key from the CRACKLE_API_KEY environment variable.

curl "https://goblins-call-api.onrender.com/v1/me" \
  -H "Authorization: Bearer $CRACKLE_API_KEY"

Check a key answers with the key’s name and the workspace it acts in, which makes it a good first request.

Creating a key

In the studio, open API keys and choose Create API key. Give it a name that says where it will be used, such as “Production server”.

A workspace can hold 25 keys at a time. The list shows each key’s name, its first and last characters, who created it and when it was last used.

Revoking a key

Choose Revoke beside a key in the studio. Requests made with it are refused with 401 within a few seconds, and that cannot be undone. Calls already in progress are not cut off; they just can no longer be managed with that key.

To replace a key without downtime, bring the new one in before taking the old one out:

Rotating a key

# 1. Create a new key in the studio and deploy it
export CRACKLE_API_KEY="ck_new_key"

# 2. Confirm the new key works
curl "https://goblins-call-api.onrender.com/v1/me" -H "Authorization: Bearer $CRACKLE_API_KEY"

# 3. Revoke the old key in the studio

An agent key is replaced in one step instead, with Rotate an agent’s key or from the studio.

What a key cannot do

Keys are created and revoked by a person signed in to the studio, never by another key, so a key that leaks cannot be used to make more. Requests to manage keys with a key answer 403. A key also cannot reach anything outside its own workspace: another workspace’s agents, calls and tools answer 404, exactly as if they did not exist.

Keeping keys safe

Keep keys on your server. Never put one in a web page, a mobile app or a public repository. What a browser or phone needs is the join token returned by POST /v1/calls, which only opens one room.
One key per place it is used. Separate keys for production, staging and each service mean you can revoke one without touching the others, and the last used time tells you which are still live.
Revoke on doubt. If a key may have been exposed, revoke it first and investigate afterwards.

When a key is refused

401UNAUTHORIZED

The key is missing, mistyped or revoked.

403FORBIDDEN

The key is valid but may not do this: an agent key outside its agent’s calls, or any key managing keys.

403ACCOUNT_SUSPENDED

The workspace’s account has been suspended.

429RATE_LIMITED

Too many requests with bad credentials from one address. Wait for the Retry-After seconds.