Skip to main content
Programmatic access to the platform uses API keys. There are two kinds, separated by a security boundary that is enforced in code: ordinary workspace keys and system keys.

​
Workspace keys

A workspace key is scoped to a single workspace and inherits a set of resource:* permissions (read, edit, delete, run, advanced, plus opt-in scopes like sandboxes:run). It’s the key you use for the SDK, REST API, and MCP server. Create one in Settings → Organization → Workspaces → (pick a workspace) → API Keys. A workspace key can read and drive resources within its workspace. It can never perform tenant-wide administration — and, by design, it can’t even hold the permissions that would allow it.

​
System keys

Some operations are tenant-wide, not workspace-scoped: creating or inviting users, creating/deleting workspaces, managing providers, billing, and org-level settings. These require the tenant-wide permissions:
Those permissions may live only on a system key — an API key homed in the tenant’s hidden admin system workspace. This is a hard invariant, enforced in two places:
  • At mint time — a request to put any tenant permission on an ordinary workspace key is rejected.
  • At resolution time — a tenant-scoped endpoint only accepts a key that actually resides in the admin system workspace, even if a permission somehow ended up on a workspace key.
The net effect: a leaked workspace key can never escalate to tenant administration. The blast radius of a workspace key is exactly its workspace.

​
Minting system keys

Only a tenant admin can create system keys. They’re managed through the admin surface:
  • SDK — client.admin.create_system_key(name, permissions=[...]). See Admin.
  • REST — POST /v1/admin/system-keys. See the System keys API.
Grant a system key only the tenant permissions it needs (e.g. a provisioning bot that creates workspaces needs workspace:create, not billing:manage).

​
Operating guidance

Scope tightly

Give each key the minimum permissions for its job. Prefer a workspace key unless the task is genuinely tenant-wide.

Rotate & revoke

Rotate keys periodically and delete unused ones. A key’s value is shown once at creation — store it in a secret manager.

Never ship in clients

Keys are secrets. Keep them server-side or in trusted environments; never embed them in browser or mobile apps.

Audit

Key-driven actions are attributed to the key. See Auditability.
See also Authentication and Authorization for how keys and permissions are verified across the platform.