surface

API authentication and scopes.

Choose a server or browser API key, grant the scopes your integration needs, configure its origin policy, and keep credentials out of public code.

Written for
Developers integrating the public REST API.
You need
Any plan for REST API access and API keys
Interactive API reference Explore endpoints, request schemas and responses. Opens in a new tab

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

Keep identity, scope and feature access separate.

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.

The complete REST scope list is:

Scope Access
account_credits:read Read credit balance
projects:read, projects:write Read and write projects
graphs:read, graphs:write Inspect and edit graph documents; document writes also need projects:write
node_types:read Discover node types
nodes:write Reserved node-write scope; no public route currently checks it
project_spend:read Read project spend
templates:read, templates:run Discover owned templates and execute their endpoints
files:read, files:write Read/download files and create uploads
runs:read, runs:execute Observe graph runs and start/cancel them
storyboards:read, storyboards:write Read and write storyboard documents
timelines:read, timelines:write Read and write timeline documents

Developer keys may additionally request cli:code for hosted Code inference. Keys expire after one year. Requests are limited to 120 per IP per minute before authentication and 600 per key per minute. A server key sent with any Origin header is refused with server_key_from_browser; use a browser key with registered origins for browser requests.

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.

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.

Last reviewed against Kaitoi on 26 October 2026. View this page as Markdown

Type at least two characters.