Authentication

Two ways in. In a browser you are already signed in, so nothing extra is needed. From a program you send an API key, and the key decides both who you are and what you may do.

1 · Browser session

Calls made from a signed-in Katama tab are authenticated by the session cookie. Fetching /api/generate from your own page needs no header. This is the path the studios use.

2 · API key

Create a key under Settings → Developer, then send it as a Bearer token against the versioned API.

curl https://katama.ai/api/v1/generate \
  -H "Authorization: Bearer kat_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "kind": "image", "prompt": "a red paper crane", "model": "flux" }'

Every live key starts with kat_live_. The key is shown once, at creation. Katama stores only a hash of it plus a short non-secret display prefix, so a lost key cannot be recovered — revoke it and create a new one.

Scopes

A key carries scopes, and the scope is checked before anything is priced or run. A key without the scope for the kind you requested is refused with 403 and spends nothing. Give a key the narrowest scope that does the job: a leaked image-only key cannot start expensive video runs.

Identity

A key acts as exactly one account — its owner. There is no impersonation parameter, and no field in the request body can change whose credits are spent. Rate limiting is per key, so one noisy integration cannot exhaust the others.

Keys belong on a server. Anything shipped to a browser is readable by whoever opens the page — bundlers do not hide it. Call Katama from your backend and pass the result on.

Errors

HTTP	Code	What it means
401	`unauthorized`	Missing, malformed, unknown or revoked key. Also: no `Bearer` in front of it.
403	`forbidden`	The key is valid but lacks the scope for this kind of request.
429	`rate_limited`	Too many requests on this key. Back off and retry.

A 429 is not a verdict on your request. It says nothing about whether the request would have been allowed — retry it and read the real answer before you conclude anything.

Next: Image generation · Video generation