From a2728439ffe37f481ceb8642186240ee5abb4898 Mon Sep 17 00:00:00 2001
From: Steven Masley <Emyrk@users.noreply.github.com>
Date: Mon, 17 Nov 2025 11:34:01 -0600
Subject: [PATCH] docs: add API key scopes documentation (#20742)

## Description

Adds a brief section to the API & Session Tokens documentation
explaining API key scopes.

## Changes

- Added "API Key Scopes" section to
`docs/admin/users/sessions-tokens.md`
- Includes overview of scope functionality and security benefits
- Documents scope format (`resource:action`) and wildcard usage
- Provides CLI examples for creating scoped tokens
- Lists common scope examples with descriptions

## Motivation

Users need documentation on how to create and use scoped API tokens for
improved security by limiting token permissions to only necessary
operations.

## Testing

- Reviewed documentation formatting
- Verified markdown structure
- Confirmed examples are accurate
---
 docs/admin/users/sessions-tokens.md | 51 +++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)

diff --git a/docs/admin/users/sessions-tokens.md b/docs/admin/users/sessions-tokens.md
index 8152c92290..901f4ae038 100644
--- a/docs/admin/users/sessions-tokens.md
+++ b/docs/admin/users/sessions-tokens.md
@@ -80,3 +80,54 @@ You can use the
 [`CODER_MAX_TOKEN_LIFETIME`](https://coder.com/docs/reference/cli/server#--max-token-lifetime)
 server flag to set the maximum duration for long-lived tokens in your
 deployment.
+
+## API Key Scopes
+
+API key scopes allow you to limit the permissions of a token to specific operations. By default, tokens are created with the `all` scope, granting full access to all actions the user can perform. For improved security, you can create tokens with limited scopes that restrict access to only the operations needed.
+
+Scopes follow the format `resource:action`, where `resource` is the type of object (like `workspace`, `template`, or `user`) and `action` is the operation (like `read`, `create`, `update`, or `delete`). You can also use wildcards like `workspace:*` to grant all permissions for a specific resource type.
+
+### Creating tokens with scopes
+
+You can specify scopes when creating a token using the `--scope` flag:
+
+```sh
+# Create a token that can only read workspaces
+coder tokens create --name "readonly-token" --scope "workspace:read"
+
+# Create a token with multiple scopes
+coder tokens create --name "limited-token" --scope "workspace:read" --scope "template:read"
+```
+
+Common scope examples include:
+
+- `workspace:read` - View workspace information
+- `workspace:*` - Full workspace access (create, read, update, delete)
+- `template:read` - View template information
+- `api_key:read` - View API keys (useful for automation)
+- `application_connect` - Connect to workspace applications
+
+For a complete list of available scopes, see the API reference documentation.
+
+### Allow lists (advanced)
+
+For additional security, you can combine scopes with allow lists to restrict tokens to specific resources. Allow lists let you limit a token to only interact with particular workspaces, templates, or other resources by their UUID:
+
+```sh
+# Create a token limited to a specific workspace
+coder tokens create --name "workspace-token" \
+  --scope "workspace:read" \
+  --allow "workspace:a1b2c3d4-5678-90ab-cdef-1234567890ab"
+```
+
+**Important:** Allow lists are exclusive - the token can **only** perform actions on resources explicitly listed. In the example above, the token can only read the specified workspace and cannot access any other resources (templates, organizations, other workspaces, etc.). To maintain access to other resources, you must explicitly add them to the allow list:
+
+```sh
+# Token that can read one workspace AND access templates and user info
+coder tokens create --name "limited-token" \
+  --scope "workspace:read" --scope "template:*" --scope "user:read" \
+  --allow "workspace:a1b2c3d4-5678-90ab-cdef-1234567890ab" \
+  --allow "template:*" \
+  --allow "user:*" \
+  ... etc
+```