## Summary Coder validates every requested API key scope against a curated public catalog in `coderd/rbac`, but the docs never listed it. Readers had to infer the requestable set from the `codersdk.APIKeyScope` enum, which is a superset that includes internal scopes a token cannot carry. This adds `scripts/scopesdocgen`, which renders `docs/reference/api-key-scopes.md` from `rbac.ExternalScopeNames` and the policy definitions behind it: - built-in scopes (`coder:all`, `coder:application_connect`) - composite `coder:*` scopes, each with the permissions it expands to - low-level `resource:action` scopes, with the action descriptions the policy declares - the deprecated `all` / `application_connect` aliases and their canonical spellings The generator is wired into `make gen`, so CI fails when the scope catalog and the page drift apart. ## Also in this change - `coderd/apikey.go`: the unrequestable-scope `400` detail pointed at `admin/users/sessions-tokens#api-key-scopes`, which only ever held a partial list. It now points at the generated reference. - `docs/admin/users/sessions-tokens.md`: the partial enumeration and the "read the schema, but not all of it applies" caveat are replaced with a link to the reference. The how-to content stays. ## Verification - `go test ./scripts/scopesdocgen` covers the sentence formatting, the scope partitioning, and a guard that every name in `rbac.ExternalScopeNames()` appears on the rendered page. - `go test ./coderd -run 'TestTokenScoped|TestCreateTokenScopes|TestExternalScopesAreStorable|TestTokenLegacySingularScopeCompat'` passes, confirming the page's claims about the default scope and the rejection of internal scopes. - `make lint/emdash`, `make lint/docs-html`, `make lint/check-scopes`, `pnpm run check-docs`, and Vale on the changed pages are clean. Full `make pre-commit` passed. <details> <summary>Context and scope decisions</summary> Part of the DOCS Automated reference documentation project, which tracks generating reference pages from product source of truth instead of maintaining them by hand. DOCS-135 is the first item: it was filed as "wire up the existing generator," but `scripts/apikeyscopesgen` emits Go (`codersdk/apikey_scopes_gen.go`), not documentation, so there was no generator output to surface and this adds one. Decisions made while implementing: - **Placement.** `docs/reference/api-key-scopes.md`, as a direct child of Reference rather than inside `docs/reference/api/`, because that directory is owned by the swagger generator. - **Page shape.** Follows the `scripts/docgenenv` convention for generated reference pages: the generated marker and page metadata in front matter, the generated-content banner in the body, and sections starting at level two because the front-matter title renders as the page heading. - **Public scopes only.** The page lists what `rbac.IsExternalScope` accepts. Internal `resource:action` pairs are deliberately excluded, which is the distinction the old schema link failed to make. - **Acronym handling.** Policy action descriptions are lowercase source strings (`"ssh into a given workspace"`). The generator restores the casing of a small set of leading acronyms rather than editing the RBAC package, so the change stays inside the docs pipeline. Sibling backlog items turned out to be already delivered and are being rescoped separately: `metricsdocgen` and `auditdocgen` already write into their docs pages, and `scripts/configdocgen` already generates the configuration reference. </details> --- Generated with Coder Agents on behalf of @nickvigilante. Linear: [DOCS-135](https://linear.app/codercom/issue/DOCS-135/wave-1-wire-up-api-key-scopes-reference-to-docs) ## Product UI impact, please read This PR corrects three RBAC action description strings in `coderd/rbac/policy/policy.go`: | Action | Before | After | |---|---|---| | `workspace:start` | allows starting a workspace | start a workspace | | `workspace:stop` | allows stopping a workspace | stop a workspace | | `api_key:update` | update an api key, eg expires | update an api key, for example its expiry | These were internal-facing until this PR, which is what made them worth fixing: the new reference page renders them verbatim to operators, and "eg expires" is not decodable by a reader without codebase context. **They are not docs-only.** `make gen` propagates them to `coderd/rbac/object_gen.go` and `site/src/api/rbacresourcesGenerated.ts`, and `CreateEditRolePageView.tsx` renders the description next to each action in the custom roles editor. So this changes admin UI copy, and `CreateEditRolePageView.stories.tsx` means Pixel may now report a genuine snapshot diff on that component rather than the pre-existing failure noted below. The new wording matches the convention the rest of the table already follows (`ssh into a given workspace`, `create an AI Gateway key`), so this makes the UI more internally consistent, not less. Flagging it explicitly because a docs PR changing product copy deserves an owner's eyes rather than a silent merge. Happy to split it out if RBAC or frontend would rather own it, with the caveat that the reference page would then publish `eg expires` in the meantime. <details> <summary>CI note: Storybook / Pixel failure</summary> The `Storybook` check fails at its `Snapshot` step, and `Pixel / Review` reports `build failed` with no snapshots processed. **Updated:** this note originally said the branch touched no files under `site/`. That is no longer true. Correcting the RBAC policy description strings (CRF-24) required `make gen`, which regenerated `site/src/api/rbacresourcesGenerated.ts` alongside `coderd/rbac/object_gen.go`. That file is a generated string table with no rendered component behind it, so it still cannot account for a Storybook snapshot or Pixel build failure, but the original justification no longer holds and is replaced by this one. The failure predates that change: it was present when the branch genuinely had no `site/` diff. Every other check passes. </details>
11 KiB
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 |
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 |