coder/docs/reference/api-key-scopes.md

title, description, icon_path

title	description	icon_path
API key scopes	Reference for the scopes an API key can request, including the built-in, composite, and low-level scopes.	./images/icons/api.svg

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
workspace_secret	create

coder:workspaces.delete

Resource	Actions
organization_member	read
template	read, use
workspace	delete, read
workspace_secret	create

coder:workspaces.operate

Resource	Actions
organization_member	read
template	read
workspace	read, start, stop, update
workspace_secret	create

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.

inbox_notification

Scope	Description
inbox_notification:read	Read inbox notifications.
inbox_notification:update	Update inbox notifications.

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.

organization_skill

Scope	Description
organization_skill:*	Every action on organization_skill, including actions not listed on this page.
organization_skill:create	Create an organization skill.
organization_skill:delete	Delete an organization skill.
organization_skill:read	Read organization skill metadata and content.
organization_skill:share	Share an organization skill with other users or groups.
organization_skill:update	Update an organization skill.

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