API keys and scopes

CrowNest authenticates API requests with org-scoped API keys, and every key carries an explicit list of scopes that defines exactly what it can do. You create and revoke keys in the dashboard, optionally restricting them to specific projects.

Organizations and projects

An organization is the tenant boundary: every sandbox, artifact, preview, and API key belongs to exactly one organization. A project is a grouping inside an organization for sandboxes, usage, quotas, and API key restrictions. Use projects to separate environments, teams, or agents that share an organization. GET /v1/projects lists the projects your key can see.

Key format and one-time display

API keys look like cn_live_... and are sent as a bearer token:

Authorization: Bearer cn_live_...

The raw key value is shown once, at creation. CrowNest stores only the prefix, a hash, and the last four characters, so the full key can't be recovered later. Store it in a secrets manager when you create it; if you lose it, revoke the key and create a new one.

[!IMPORTANT] API keys are managed in the dashboard only. Keys can't create or revoke other keys — the api_key:read scope is reserved for human sessions and can never be granted to an API key.

Scopes

Scopes are singular resource:action strings. A request succeeds only if the key holds the scope the endpoint requires; otherwise it returns forbidden.

Some operations need more than one scope: running a command with collect requires command:run plus artifact:create, and creating an artifact requires artifact:create plus file:read.

Dashboard presets

The dashboard offers presets so you don't assemble scope lists by hand:

• Quickstart Developer — full sandbox, command, file, artifact, and preview management, plus usage:read. Good for getting started.
• Project Runtime — the runtime scopes without artifact:delete and preview:revoke. Good for agents that create and use sandboxes but must not remove durable resources.
• Read Only — sandbox:read, command:read, file:read, artifact:read, preview:read, and usage:read. Good for dashboards and monitoring.

You can also pick a custom scope set. We recommend granting the smallest set that covers what the key actually does.

Project-restricted keys

A key is org-scoped by default, but you can restrict it to specific projects when you create it. A restricted key can only act on resources in those projects; requests against anything else return forbidden or not_found. Use project restrictions to keep one agent's credentials away from another project's sandboxes.

Scopes API keys can never hold

Two areas are off limits to API keys regardless of configuration:

• api_key:read — key management is human-session only, in the dashboard.
• Any scope outside the table above — keys can't be granted scopes that don't exist in the public scope set.

Next steps

• Usage and billing — what usage:read exposes.
• Sandboxes — the resources these scopes govern.
• SDK quickstart — use a key from the SDK.
• API reference