API key scopes

On this page

A scope limits what an API key can do. A scoped key never exceeds the permissions of the user who created it: Coder checks the scope and the user's roles on every request, so a scope narrows access and never widens it.

Pass --scope once per scope when you create a token:

coder tokens create --scope coder:workspaces.access --scope template:read

A token created without an explicit scope uses coder:all, which grants the full permissions of its owner. To create and revoke tokens, refer to Sessions & API Tokens.

This page lists every canonical scope a token can request and the deprecated names Coder accepts for backward compatibility. Coder rejects any scope name not listed on this page with a 400 response.

Built-in scopes

Built-in scopes cover the two broadest cases: the full permissions of the owner, and connections to workspace applications.

Scope	Grants
`coder:all`	All operations.
`coder:application_connect`	Ability to connect to applications.

Composite scopes

A composite scope groups the permissions that one task needs, so you can scope a token to that task without listing each permission. Each scope below grants the permissions in its table.

`coder:apikeys.manage_self`

Resource	Actions
`api_key`	`create`, `delete`, `read`, `update`

`coder:templates.author`

Resource	Actions
`file`	`create`, `read`
`template`	`create`, `delete`, `read`, `update`, `view_insights`

`coder:templates.build`

Resource	Actions
`file`	`create`, `read`
`provisioner_jobs`	`read`
`template`	`read`

`coder:workspaces.access`

Resource	Actions
`organization_member`	`read`
`template`	`read`
`workspace`	`application_connect`, `read`, `ssh`

`coder:workspaces.create`

Resource	Actions
`organization_member`	`read`
`template`	`read`, `use`
`workspace`	`create`, `read`, `start`, `stop`, `update`

`coder:workspaces.delete`

Resource	Actions
`organization_member`	`read`
`template`	`read`, `use`
`workspace`	`delete`, `read`

`coder:workspaces.operate`

Resource	Actions
`organization_member`	`read`
`template`	`read`
`workspace`	`read`, `start`, `stop`, `update`

Low-level scopes

A low-level scope grants one action on one resource, written as resource:action. Combine low-level scopes when no composite scope matches the task.

The resource:* form grants every action on that resource, including actions not listed on this page.

`api_key`

Scope	Description
`api_key:*`	Every action on `api_key`, including actions not listed on this page.
`api_key:create`	Create an API key.
`api_key:delete`	Delete an API key.
`api_key:read`	Read API key details (secrets are not stored).
`api_key:update`	Update an API key, for example its expiry.

`chat_model_config`

Scope	Description
`chat_model_config:read`	Read chat model configs.
`chat_model_config:share`	Share a chat model config with other users or groups.

`file`

Scope	Description
`file:*`	Every action on `file`, including actions not listed on this page.
`file:create`	Create a file.
`file:read`	Read files.

`organization`

Scope	Description
`organization:*`	Every action on `organization`, including actions not listed on this page.
`organization:delete`	Delete an organization.
`organization:read`	Read organizations.
`organization:update`	Update an organization.

`template`

Scope	Description
`template:*`	Every action on `template`, including actions not listed on this page.
`template:create`	Create a template.
`template:delete`	Delete a template.
`template:read`	Read template.
`template:update`	Update a template.
`template:use`	Use the template to initially create a workspace, then workspace lifecycle permissions take over.

`user`

Scope	Description
`user:*`	Every action on `user`, including actions not listed on this page.
`user:read`	Read user data.
`user:read_personal`	Read personal user data like user settings and auth links.
`user:update_personal`	Update personal data.

`user_secret`

Scope	Description
`user_secret:*`	Every action on `user_secret`, including actions not listed on this page.
`user_secret:create`	Create a user secret.
`user_secret:delete`	Delete a user secret.
`user_secret:read`	Read user secret metadata and value.
`user_secret:update`	Update user secret metadata and value.

`user_skill`

Scope	Description
`user_skill:*`	Every action on `user_skill`, including actions not listed on this page.
`user_skill:create`	Create a user skill.
`user_skill:delete`	Delete a user skill.
`user_skill:read`	Read user skill metadata and content.
`user_skill:update`	Update user skill metadata and content.

`workspace`

Scope	Description
`workspace:*`	Every action on `workspace`, including actions not listed on this page.
`workspace:application_connect`	Connect to workspace apps via browser.
`workspace:create`	Create a new workspace.
`workspace:delete`	Delete workspace.
`workspace:read`	Read workspace data to view on the UI.
`workspace:ssh`	SSH into a given workspace.
`workspace:start`	Start a workspace.
`workspace:stop`	Stop a workspace.
`workspace:update`	Edit workspace settings (scheduling, permissions, parameters).

Deprecated scope names

Coder still accepts the following names and stores each one as its canonical equivalent. Use the canonical name.

Deprecated name	Canonical name
`all`	`coder:all`
`application_connect`	`coder:application_connect`