Files
coder/docs/reference/api-key-scopes.md
T
Nick Vigilante 4a184ca54a feat: add generated API key scopes reference (DOCS-135) (#29307)
## 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>
2026-10-01 16:09:01 -04:00

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