Skip to main content
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:
  1. Select a preset - Choose from deploy, read-only, agent-runner, or custom
  2. Configure scopes - Add/remove permission scopes for specific resources
  3. Choose sharing groups - Select which groups receive access to key-created resources
  4. 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:
PresetIconDefault ScopesUse Case
Deploy:rocket:namespace:admin, agent:editor, project:editorCI/CD pipelines, deployments
Read-Only:eye:agent:viewer, project:viewerMonitoring, dashboards
Agent Runner:robot:agent:viewer, project:editorExecute 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 TypeValid Roles
orgadmin, member
namespaceadmin
projectdiscoverer, viewer, editor, owner
agentdiscoverer, 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"}

​
Sharing Groups

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:
  1. Key creation - The key’s service user is added as a member to each sharing group
  2. Resource creation - When the key creates an agent/project, each sharing group gets owner role
  3. 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.