Authentication

One header, one key, one organisation.

The header

Every /v1 request carries your key in X-Api-Key. It is a dedicated header rather than Authorization, deliberately: the API also serves a browser-facing surface authenticated with JWTs, and keeping the two on separate headers means neither can accidentally reach the other's endpoints.

curl https://api.askamy.co.za/v1/runs/01936c2f-6d1a-7f60-9a53-2f0f1c9a77e1 \
  -H "X-Api-Key: $AMY_API_KEY"

Getting a key

• Who can mint one: an organisation Admin, from the Console under API keys. A key cannot mint another key. Before the first call, set up your organisation.
• Shown once. The full key appears when it is issued and cannot be recovered afterwards. Lose it and the key is replaced, not recovered.
• Expiry is optional. Give a key a lifetime of 1 to 3,650 days when you mint it, or leave it without one. An expired key is refused like a revoked one.
• Your plan caps how many keys are live at once. Revoked and expired keys do not count against the cap. A mint that would go over it is refused with a 403 (see Errors).
• Revoking takes effect at once. A revoked key is refused on its very next request; nothing caches it.

Key format

A key reads amy_live_<keyId>.<secret>. The keyId half is not secret — it is what the server looks the key up by. The secret half is stored only as a hash on our side, which is why it is shown exactly once at issue.

What a key is scoped to

• One organisation. The key resolves your organisation; you never send a tenant, organisation or customer id, and you cannot address another one. A run started with your key can only ever see your organisation's data.
• One API client, shared by all your keys. Every key an organisation mints belongs to the same API client, and the client is the unit that owns runs, conversations and uploaded files: any of your keys can read and cancel what any other started, and a rotated key picks up exactly where the old one left off. Keys do not separate your products from one another. If two products must not see each other's runs and conversations, give each its own organisation, and so its own keys.
• No scopes, no narrower keys. A key can call everything under /v1 and nothing else. There is no read-only key and no per-agent key.
• The /v1 surface only. A key cannot call the Console API, and a Console session cannot call /v1. Agents, schedules, registered MCP servers, provider keys, webhooks and usage totals are set up and read in the Console; a key cannot manage them.
• Your end users are yours. Pass endUserRef to attribute a run to one of your own users. It must be a stable pseudonymous handle — your own user id or an opaque token — and never personal data: no email, name, phone or government id. It is retained in audit records, and it is the handle an erasure of that user's data is made against. An API key cannot request an erasure; an organisation Admin does.

Failures

• 401 — missing, malformed, unknown, revoked or expired key. The body is ProblemDetails; the response says nothing about which of those it was, on purpose.
• 403 — the key is fine, but your plan will not allow the call: for example a monthly limit on Amy-provided model access (calls on your own provider key do not count towards it) or the file storage allowance; see Usage.
• 404 — including for a resource that exists but belongs to someone else, or to another API client. A cross-tenant read is never a 403, because a 403 would confirm the thing exists.
• 429 — too many requests for your API client in the last minute. Wait for the seconds in the Retry-After header.

Handling keys

• Keep keys server-side. A key in a browser or a mobile binary is a public key.
• Mint a key per deployment or environment, so revoking one does not take the others down. They still share one client (above), so this is for revocation and expiry, not for separating data.
• Treat a leaked key as spent: revoke it and mint a replacement rather than hoping.
• Give keys an expiry where you can, and rotate before it: mint the new key, deploy it, then revoke the old one.