API Keys

API keys authenticate programmatic access to Terminal Use resources. Each key has scopes that define what resources it can access and sharing groups that determine transitive permissions.

API keys are for authentication. For webhook signing secrets (Slack, GitHub), see List Webhook Keys.

Platform UI

The platform provides a guided wizard for creating API keys:

Select a preset - Choose from deploy, read-only, agent-runner, or custom
Configure scopes - Add/remove permission scopes for specific resources
Choose sharing groups - Select which groups receive access to key-created resources
Review and create - Confirm settings and generate the key

Access the wizard from Access Control → API Keys → Create API Key in the dashboard.

Key Presets

Presets provide sensible default scopes for common use cases:

Preset	Icon	Default Scopes	Use Case
Deploy	:rocket:	`namespace:admin`, `agent:editor`, `project:editor`	CI/CD pipelines, deployments
Read-Only	:eye:	`agent:viewer`, `project:viewer`	Monitoring, dashboards
Agent Runner	:robot:	`agent:viewer`, `project:editor`	Execute tasks, manage files
Custom	:gear:	(none)	Manual scope configuration

Presets auto-populate scopes in the creation wizard. You can modify them before creating the key.

Scopes

Each scope grants a role on a specific resource. Scopes follow this structure:

{
  "resource_type": "agent",
  "resource_id": "agt_xxx",
  "role": "editor"
}

Valid Roles by Resource Type

Resource Type	Valid Roles
`org`	`admin`, `member`
`namespace`	`admin`
`project`	`discoverer`, `viewer`, `editor`, `owner`
`agent`	`discoverer`, `viewer`, `editor`, `owner`, `executor`

The executor role is legacy and is normalized to viewer internally, but still grants run permission.

Scope Examples

Namespace admin - Full control over a namespace and its contents:

{"resource_type": "namespace", "resource_id": "ns_xxx", "role": "admin"}

Agent viewer - Read access and ability to run tasks:

{"resource_type": "agent", "resource_id": "agt_xxx", "role": "viewer"}

Project editor - Create and modify files in a project:

{"resource_type": "project", "resource_id": "prj_xxx", "role": "editor"}

API keys can be members of sharing groups. When a key creates a resource (agent or project), sharing groups automatically receive owner access to that resource. How it works:

Key creation - The key’s service user is added as a member to each sharing group
Resource creation - When the key creates an agent/project, each sharing group gets owner role
Effect - All members of the sharing groups automatically get owner access

This enables team workflows where:

A deploy key creates agents during CI
The engineering team’s group automatically gets owner access to those agents
Team members can manage and debug without manual permission grants

A key with no sharing groups can create resources that only it can access. Always assign at least one sharing group for team visibility.

Get Started

Core Concepts

Build Agents

Deploy & Operate

Security & Access

API

Platform UI

Key Presets

Scopes

Valid Roles by Resource Type

Scope Examples

​Platform UI

​Key Presets

​Scopes

​Valid Roles by Resource Type

​Scope Examples

​Sharing Groups

Platform UI

Key Presets

Scopes

Valid Roles by Resource Type

Scope Examples

Sharing Groups