# API key scopes

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](/beta-docs/@main/admin/users/sessions-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]

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 [#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` [#coderapikeysmanage_self]

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

### `coder:templates.author` [#codertemplatesauthor]

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

### `coder:templates.build` [#codertemplatesbuild]

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

### `coder:workspaces.access` [#coderworkspacesaccess]

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

### `coder:workspaces.create` [#coderworkspacescreate]

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

### `coder:workspaces.delete` [#coderworkspacesdelete]

| Resource              | Actions          |
| --------------------- | ---------------- |
| `organization_member` | `read`           |
| `template`            | `read`, `use`    |
| `workspace`           | `delete`, `read` |
| `workspace_secret`    | `create`         |

### `coder:workspaces.operate` [#coderworkspacesoperate]

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

## Low-level scopes [#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` [#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` [#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` [#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` [#inbox_notification]

| Scope                       | Description                 |
| --------------------------- | --------------------------- |
| `inbox_notification:read`   | Read inbox notifications.   |
| `inbox_notification:update` | Update inbox notifications. |

### `organization` [#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` [#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` [#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` [#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` [#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` [#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` [#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 [#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` |