Files
coder/docs/reference/api-key-scopes.md
T
Ehab Younes f0e2fce326 fix: let scoped tokens list and mark inbox notifications read (#30176)
`inbox_notification:read` and `inbox_notification:update` existed but weren't
in the public scope catalog, so only `coder:all` tokens could use the inbox.
The inbox endpoints also returned 500s or a clean socket close when a scope
was missing, instead of a 403.

- Add `inbox_notification:read` and `inbox_notification:update` to the public
  scope catalog. `create` stays internal, so there is no
  `inbox_notification:*`. No migration is needed.
- Every inbox endpoint checks scopes up front and returns 403 naming the
  missing scope. The watch endpoint checks before the websocket upgrade.
- `read-status` requires both `read` and `update`. It returns 404 unless the
  notification belongs to the caller, so an owner can no longer mark another
  user's notification read.
2026-10-06 13:01:11 +03:00

203 lines
11 KiB
Markdown
Generated

---
# 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"
---
<!-- DO NOT EDIT | GENERATED CONTENT -->
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` |
### `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. |
### `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. |
### `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` |