API authentication and scopes.

Public REST requests use an API key in Authorization: Bearer <key>. Create keys through Settings → Developer → API Keys and grant only the scopes the integration needs. A browser login cookie is not a substitute for that public API credential.

#See what a key actually authorizes

A REST key identifies its owner and grants selected scopes; entitlement and workspace permissions are additional checks. Keep service-account keys on a trusted backend. A browser key is intentionally visible and uses configured origins as an additional restriction, not user authentication. A public interface must still enforce authorization. Never put a secret in a URL. Endpoint credentials and MCP OAuth have their own contracts.

The server route places its secret inside the backend’s boundary. The direct browser route passes through the registered-origin and active-Developer-App checks with a visible browser key; neither path removes application-user authorization.

#Choose where the key will run

Server keys belong in your application backend or another trusted execution environment. Do not embed a server key in JavaScript sent to a visitor or use it as a substitute for a browser key in your web application.

Browser keys belong to an active Developer App and use its registered origins. To create one:

1. Open Settings → Developer → Apps and create a Developer App.
2. Register each exact origin your application uses, including its scheme, hostname, and non-default port. For example, https://example.com and http://localhost:3000 are different origins.
3. Use HTTPS for deployed origins. HTTP is allowed only for localhost development. Paths, query strings, fragments, and wildcard hosts are not allowed.
4. Return to API Keys, choose Browser app, and attach the key to that app. Grant only the scopes the page needs.

Apps and browser-key creation require the corresponding account capability; the settings show an upgrade requirement when it is missing. Treat the key as visible to the person running the page. Disabling the app or sending a request from an unregistered origin can make the request fail.

Keep the user-facing application and its backend boundary explicit. For most multi-user applications, the backend owns the Kaitoi credential and decides which authorized application user may submit each job.

#Grant the right scope

Read access and execution are separate. For example, discovering template endpoints needs the appropriate read scope, while submitting a run needs the run scope. The interactive API reference lists each endpoint's requirements. A valid key can still lack a scope or account capability.

Use separate keys for integrations with different privileges or lifetimes. Revoke or rotate a key when its access should end or you believe it was exposed.

#Understand ownership identifiers

An API principal comes from the authenticated key. Developer-supplied externalUserId and externalWorkspaceId label or guard your application's resources; they do not sign in as another Kaitoi user or grant team membership. Enforce your application's own user authorization before using its shared key.

#Handle refusals

Check the structured error. Authentication, scope/capability, origin, rate-limit, validation, and concurrency failures need different responses. Do not retry an authorization error as a new paid submission. Never log the full Authorization header or include a real key in an error report or public example.

#Map the caller to the allowed operation

Backend key: keep its bearer secret in a trusted server or CLI process. Browser key: attach it to an active Developer App and registered origins; it remains visible to the browser user. Application user: enforce who may use your shared credential and resources. External identifiers label or guard resources; they do not impersonate another Kaitoi user. No key is created here.

#Checks and next steps

Scopes are specific: runs:execute creates or cancels public graph runs; runs:read observes them. Project metadata uses projects:read/write, while editable graph documents also require graphs:read/write as documented. Files, templates, timelines, and storyboards have separate scopes. There is no generic REST runs:write scope.

Browser origin policy and your application's user authorization solve different problems. A registered origin is not proof that a visitor may spend your application's credits or access another user's resources. Enforce that policy in your application. Account capabilities remain necessary even when the key has a scope.

Do not reuse a REST key as an MCP credential or a browser login cookie as a public API key. For application contracts and key placement, see Build applications with Kaitoi.