`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.
203 lines
11 KiB
Markdown
Generated
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` |
|