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:
Authorization: Bearer zr_live_your_key_here# or, as Anthropic's SDKs send it:x-api-key: zr_live_your_key_hereKeys 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.
/connectnamestring- What the agent calls itself, shown on the approval page; the key is named after it. Optional.
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.
/connect/keydevice_codestringrequired- From POST /connect.
waitseconds- How long to wait for the approval before answering pending, 0 to 25. Defaults to 25.
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"}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,
productionandstaging), 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
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.