# 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.

Source: https://kaitoi.io/docs/core/authentication/
Section: Kaitoi Core / REST API
Written for: Developers integrating the public REST API.
Last reviewed: 2026-10-24

---

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.

*Figure: Keep identity, scope and feature access separate.*

## 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](/docs/core/mcp-apps/).