From b00e1e443b5183f410b2900296c88d0272c5e4b6 Mon Sep 17 00:00:00 2001 From: Steven Masley Date: Wed, 12 Nov 2025 11:08:08 -0600 Subject: [PATCH 1/7] docs: add API key scopes documentation Add a section to the sessions-tokens documentation explaining API key scopes, including: - Overview of scope functionality and security benefits - Scope format (resource:action) and wildcard usage - CLI examples for creating scoped tokens - Common scope examples with descriptions --- docs/admin/users/sessions-tokens.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/docs/admin/users/sessions-tokens.md b/docs/admin/users/sessions-tokens.md index 8152c92290877..2e208e11bae0d 100644 --- a/docs/admin/users/sessions-tokens.md +++ b/docs/admin/users/sessions-tokens.md @@ -80,3 +80,32 @@ 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. + From c29770646ece401e11e8724c1dd373cd3ab3ac13 Mon Sep 17 00:00:00 2001 From: Steven Masley Date: Wed, 12 Nov 2025 11:41:44 -0600 Subject: [PATCH 2/7] docs: add allow lists section for API key scopes Add documentation for allow lists as an advanced feature that can be combined with scopes to restrict tokens to specific resource UUIDs. --- docs/admin/users/sessions-tokens.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/admin/users/sessions-tokens.md b/docs/admin/users/sessions-tokens.md index 2e208e11bae0d..73989904232d4 100644 --- a/docs/admin/users/sessions-tokens.md +++ b/docs/admin/users/sessions-tokens.md @@ -109,3 +109,16 @@ Common scope examples include: 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 +``` + +This creates a token with `workspace:read` scope that can only access the specified workspace, even if the user has access to other workspaces. + From d710eae952c0f8a49342405264586608ba3005b3 Mon Sep 17 00:00:00 2001 From: Steven Masley Date: Wed, 12 Nov 2025 11:44:55 -0600 Subject: [PATCH 3/7] docs: clarify exclusive nature of allow lists Make it explicit that allow lists are exclusive - tokens can ONLY act on resources in the allow list. Add example showing how to maintain access to other resources by being exhaustive with allow list entries. --- docs/admin/users/sessions-tokens.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/admin/users/sessions-tokens.md b/docs/admin/users/sessions-tokens.md index 73989904232d4..3f0a486adfd1d 100644 --- a/docs/admin/users/sessions-tokens.md +++ b/docs/admin/users/sessions-tokens.md @@ -120,5 +120,14 @@ coder tokens create --name workspace-token \ --allow workspace:a1b2c3d4-5678-90ab-cdef-1234567890ab ``` -This creates a token with `workspace:read` scope that can only access the specified workspace, even if the user has access to other workspaces. +**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 organizations +coder tokens create --name limited-token \ + --scope workspace:read --scope template:* --scope organization:* \ + --allow workspace:a1b2c3d4-5678-90ab-cdef-1234567890ab \ + --allow template:* \ + --allow organization:* +``` From c527754abf63cdfd243cc14ef97d80aa07cbc502 Mon Sep 17 00:00:00 2001 From: Steven Masley Date: Wed, 12 Nov 2025 11:45:39 -0600 Subject: [PATCH 4/7] docs: add '... etc' to allow lists example Emphasize the exhaustive nature of allow lists by showing that additional entries would be needed. --- docs/admin/users/sessions-tokens.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/admin/users/sessions-tokens.md b/docs/admin/users/sessions-tokens.md index 3f0a486adfd1d..a37d6a17394fe 100644 --- a/docs/admin/users/sessions-tokens.md +++ b/docs/admin/users/sessions-tokens.md @@ -128,6 +128,7 @@ coder tokens create --name limited-token \ --scope workspace:read --scope template:* --scope organization:* \ --allow workspace:a1b2c3d4-5678-90ab-cdef-1234567890ab \ --allow template:* \ - --allow organization:* + --allow organization:* \ + ... etc ``` From 1179cbe334177493e4e2b0ce2141386fed0aa52f Mon Sep 17 00:00:00 2001 From: Steven Masley Date: Wed, 12 Nov 2025 11:47:29 -0600 Subject: [PATCH 5/7] docs: fix invalid scope in allow lists example Replace organization:* with user:read which is a valid scope. --- docs/admin/users/sessions-tokens.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/admin/users/sessions-tokens.md b/docs/admin/users/sessions-tokens.md index a37d6a17394fe..d2769bd4a539f 100644 --- a/docs/admin/users/sessions-tokens.md +++ b/docs/admin/users/sessions-tokens.md @@ -123,12 +123,12 @@ coder tokens create --name workspace-token \ **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 organizations +# Token that can read one workspace AND access templates and user info coder tokens create --name limited-token \ - --scope workspace:read --scope template:* --scope organization:* \ + --scope workspace:read --scope template:* --scope user:read \ --allow workspace:a1b2c3d4-5678-90ab-cdef-1234567890ab \ --allow template:* \ - --allow organization:* \ + --allow user:* \ ... etc ``` From af5e24cbaa334afb568e8d23b5b83ff63cec000c Mon Sep 17 00:00:00 2001 From: Steven Masley Date: Wed, 12 Nov 2025 11:48:07 -0600 Subject: [PATCH 6/7] docs: quote all flag arguments in examples --- docs/admin/users/sessions-tokens.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/admin/users/sessions-tokens.md b/docs/admin/users/sessions-tokens.md index d2769bd4a539f..dcb1cece4278d 100644 --- a/docs/admin/users/sessions-tokens.md +++ b/docs/admin/users/sessions-tokens.md @@ -93,10 +93,10 @@ 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 +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 +coder tokens create --name "limited-token" --scope "workspace:read" --scope "template:read" ``` Common scope examples include: @@ -115,20 +115,20 @@ For additional security, you can combine scopes with allow lists to restrict tok ```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 +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:* \ +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 ``` From b686d43119d7703e193081858ca22754c5fc2052 Mon Sep 17 00:00:00 2001 From: Steven Masley Date: Wed, 12 Nov 2025 12:44:46 -0600 Subject: [PATCH 7/7] linting --- docs/admin/users/sessions-tokens.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/admin/users/sessions-tokens.md b/docs/admin/users/sessions-tokens.md index dcb1cece4278d..901f4ae038cd3 100644 --- a/docs/admin/users/sessions-tokens.md +++ b/docs/admin/users/sessions-tokens.md @@ -130,5 +130,4 @@ coder tokens create --name "limited-token" \ --allow "template:*" \ --allow "user:*" \ ... etc -``` - +```