Get started

API keys and authentication

Every request carries an API key. Keys belong to a workspace and spend its balance; each can be held to its own budgets, models and addresses.

Sending the key

Either header works on every endpoint:

Headers
Authorization: Bearer zr_live_your_key_here
# or, as Anthropic's SDKs send it:
x-api-key: zr_live_your_key_here

Keys start with zr_live_. You see the full key once, when you create it; we only keep a hash, so nobody (us included) can show it to you again. Lost it? Revoke it and make another.

Connecting an AI agent

An agent (OpenClaw, Hermes, Manus, or your own) can get a key of its own without anyone copying one: it asks for a link, its person approves it on zurelay.com with a daily limit, and the agent collects the key. It works like signing in to a TV (OAuth’s device flow, RFC 8628). No key is needed for these two calls.

POST/connect
namestring
What the agent calls itself, shown on the approval page; the key is named after it. Optional.
Ask for a link
curl -X POST https://api.zurelay.com/connect \
-H "Content-Type: application/json" \
-d '{"name": "OpenClaw"}'
{
"status": "pending",
"device_code": "zr_dc_…",
"user_code": "WDJB-MJHT",
"verification_uri": "https://zurelay.com/connect",
"verification_uri_complete": "https://zurelay.com/connect?code=WDJB-MJHT",
"expires_in": 900,
"interval": 2
}

Show the person verification_uri_complete and the code. They sign in, check the code matches, pick the workspace and a daily limit, and approve within 15 minutes. Keep device_code to the agent: it’s what collects the key.

POST/connect/key
device_codestringrequired
From POST /connect.
waitseconds
How long to wait for the approval before answering pending, 0 to 25. Defaults to 25.
Collect the key
curl -X POST https://api.zurelay.com/connect/key \
-H "Content-Type: application/json" \
-d '{"device_code": "zr_dc_…"}'
{
"status": "approved",
"api_key": "zr_live_…",
"key_name": "OpenClaw",
"workspace": "Acme",
"daily_limit_usd": 10,
"base_url": "https://api.zurelay.com/v1"
}
HTTPstatusMeans
202pendingNot approved yet. Call again; each call waits up to 25 seconds.
200approvedHere’s the key. Asking again within 30 minutes of the approval gives the same key, in case an answer was lost.
403deniedThe person declined.
410expiredNot approved within 15 minutes, or collected too late. Start again.
410revokedThe key was revoked on the API keys page.
404unknownNo request has this device code.
The key is an ordinary key on the API keys page, named after the agent, with the daily limit the person chose. Change its rules there, or revoke it to disconnect the agent. Agents also read setup steps from zurelay.com/skill.md.

Keeping keys safe

  • Keep keys in a secret manager or environment variables, never in code or a repository.
  • Call Zurelay from your server. A key in a browser or a mobile app can be read by anyone who has the app.
  • Use one key per app or environment (say, production and staging), so you can revoke one without touching the others.
  • Give each key only what it needs: a budget, the models it calls, the addresses it runs on. See Key limits and rules.
  • If a key leaks, revoke it under API keys. Requests with it stop within 15 seconds.

What a key can be held to

Monthly budgetUSD
Spend allowed per calendar month (UTC).
Daily budgetUSD
Spend allowed per day (UTC).
Rate limitrequests / minute
Requests per minute; more are refused with 429.
Expirydate
After it, the key stops working.
Allowed modelslist
Only these models; anything else is refused with 403.
Allowed IP addresseslist
Only requests from these addresses or ranges.
Smart routingsetting
What happens when a model is down: see Smart routing.

Authentication errors

StatusCodeMeans
401missing_api_keyNo key in the request.
401invalid_api_keyThe key doesn’t exist or was revoked.
401expired_api_keyThe key passed its expiry date.
403ip_not_allowedThe key only works from other addresses.
403model_not_allowedThe key isn’t allowed to use this model.
402insufficient_quotaThe workspace balance, less what its running requests have set aside, doesn’t cover this request.
Every chat, image and video response carries an x-request-id header. Include it when you write to support and we can find the request in seconds.

Questions, or something missing? Ask our support team and we’ll answer by email, usually within a minute.