API keys and scopes

CrowNest authenticates API requests with org-scoped API keys, and every key carries an explicit list of scopes that defines what it can do. You create keys in the dashboard and revoke them from the dashboard or the API, 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:

Request header

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 can never create other API keys. Grant api_key:read and api_key:revoke only to trusted org-wide automation that rotates or disables credentials.

Scopes

Each scope is a single resource:action string. A request succeeds only if the key holds the scope the endpoint requires; otherwise it returns forbidden.

Scope	Grants
`sandbox:create`	Create sandboxes.
`sandbox:read`	Get and list sandboxes.
`sandbox:kill`	Destroy sandboxes.
`sandbox:extend`	Extend sandbox TTL.
`command:run`	Run and start commands.
`command:read`	Get commands, read logs, and follow log streams.
`command:cancel`	Cancel running commands.
`code:run`	Run code and manage code contexts.
`workspace_run:create`	Create, upload, and start Workspace Runs.
`workspace_run:read`	Read Workspace Run status, events, and evidence.
`workspace_run:cancel`	Cancel active Workspace Runs.
`file:read`	List, stat, read, and download workspace files.
`file:write`	Write, move, delete files, and create directories.
`artifact:create`	Export artifacts, including command `collect`.
`artifact:read`	Get, list, and download artifacts.
`artifact:delete`	Delete artifacts.
`preview:create`	Create previews.
`preview:read`	Get and list previews.
`preview:revoke`	Revoke previews.
`usage:read`	Read usage and quota information.
`api_key:read`	List and inspect API key metadata.
`api_key:revoke`	Revoke API keys.
`project:create`	Create projects with an org-wide key.

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. Workspace Runs with explicit artifact collection require workspace_run:create, artifact:create, and file:read.

Dashboard presets

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

Quickstart Developer — full sandbox, command, file, artifact, Workspace Run, 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, workspace_run: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.

API-key management is always org-level. Project-restricted keys cannot list, inspect, or revoke API keys even if they include api_key:read or api_key:revoke.

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