Authentication

Every request to the Public API is authenticated with an API key sent in the X-API-Key header. There is no OAuth flow, no session cookie, and no bearer token — just the one header.

Generating an API key

1. Sign in to Elizon and go to Settings → API Keys.
2. Click Create Key, give it a name, and optionally set a per-key rate limit, a monthly spend cap, and an expiry date.
3. Copy the key immediately — the full value is shown once, at creation time. Elizon stores only a hash of it; if you lose it, revoke it and create a new one.

Key format and header

Keys are prefixed elz_ followed by a random 64-character hex string, e.g. elz_9f2a...c81b. Send it on every request as:

X-API-Key: elz_<your-key>

curl https://api.elizon.com/api/v1/organizations/limits \
  -H "X-API-Key: elz_your_key_here"

A request with no X-API-Key header, or a value that doesn't start with elz_, is rejected before any database lookup:

401 Unauthorized
{ "error": "unauthorized", "message": "Valid API key required. Provide X-API-Key: elz_<your-key>." }

Org-scoped vs. project-scoped keys

Every key is either org-scoped or project-scoped, decided when the key is created:

• Org-scoped keys see every agent in the organization. You may narrow a request to one project with the project_ref_id query parameter (see GET /agents) — omit it to see everything.
• Project-scoped keys are silently restricted to the one project they were created for. Any project_ref_id you pass is ignored, and any agent outside that project returns 403 forbidden (not 404) if you address it directly by ID — the agent exists, your key just can't reach it.

There's no separate "scope" field returned by the API; scope is a property of the key itself, fixed at creation.

Key expiry

If a key was created with an expiresAt date, requests made after that date fail with the same generic 401 shown below — Elizon does not distinguish "expired" from "invalid" in the response body, so don't build logic that branches on the error message:

401 Unauthorized
{ "error": "unauthorized", "message": "API key has been revoked or expired" }

Key revocation

Revoking a key (Settings → API Keys → Revoke) takes effect within one cache TTL — up to 60 seconds — not instantly. During that window a very recently revoked key may still authenticate successfully; after it, every request with that key returns the same 401 shown above.