--- # Code generated by make gen. DO NOT EDIT. title: API key scopes description: "Reference for the scopes an API key can request, including the built-in, composite, and low-level scopes." icon_path: "./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: ```shell 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](../admin/users/sessions-tokens.md). 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` |