# API keys and scopes (/docs/concepts/api-keys)



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 [#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 [#key-format-and-one-time-display]

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

```text title="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.

<Callout type="warn" title="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.
</Callout>

## Scopes [#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 [#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 [#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 [#next-steps]

* [Usage and billing](/docs/concepts/usage-and-billing) — what `usage:read`
  exposes.
* [Sandboxes](/docs/concepts/sandboxes) — the resources these scopes
  govern.
* [SDK quickstart](/docs/quickstart/sdk) — use a key from the SDK.
* [API reference](/docs/api/overview)