Authentication

Every API request authenticates with an organization-scoped API key sent as a Bearer token. Keys carry a set of scopes that determine which actions they can perform, and you can optionally restrict a key to specific projects.

API keys

Pass your key in the Authorization header on every request:

curl https://api.crownest.dev/v1/sandboxes \
  -H "Authorization: Bearer $CROWNEST_API_KEY"

Keys look like cn_live_.... The raw value is shown exactly once, at creation time — CrowNest stores only the key prefix, a hash, and the last four characters, so you can't retrieve a key again later. Store it in a secret manager or an environment variable such as CROWNEST_API_KEY.

You create and revoke API keys in the dashboard. Keys can't manage other keys: there is no API endpoint for key management, which limits the blast radius of a leaked key.

Scopes

Each scope is a singular resource:action string, such as sandbox:create. A key can only call endpoints whose required scope it holds. Every endpoint in this reference lists its required scope.

The dashboard offers scope presets when you create a key:

• Quickstart Developer — full sandbox, command, file, artifact, and preview management, plus usage:read. Use this for development.
• Project Runtime — runtime scopes without the destructive artifact:delete and preview:revoke. Use this for production workloads.
• Read Only — sandbox:read, command:read, file:read, artifact:read, preview:read, and usage:read. Use this for monitoring and dashboards.

Project-restricted keys

Keys are org-scoped by default and can reach every project in the organization. You can restrict a key to one or more projects when you create it in the dashboard. A project-restricted key can only see and act on resources in its allowed projects; resources elsewhere return not_found or forbidden.

401 vs 403

The API distinguishes between authentication and authorization failures:

• 401 — the request isn't authenticated. The key is missing, malformed, invalid, or revoked. Error codes: unauthenticated or invalid_api_key. Fix the credential.
• 403 — the request is authenticated, but the key lacks the required scope or has no access to the resource. Error code: forbidden. Fix the key's scopes or project restrictions.

Next steps

• Learn the error envelope in Errors.
• Create a sandbox in Sandboxes.