Adds the database table, queries, and permissions for workspace secrets: secrets set on a workspace build and delivered to the agent, never to Terraform. Each secret belongs to one workspace build. A new build copies the previous build's secrets, then the old copies lose their values but stay as history.
217 lines
12 KiB
Markdown
Generated
217 lines
12 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` |
|
|
| `workspace_secret` | `create` |
|
|
|
|
### `coder:workspaces.delete`
|
|
|
|
| Resource | Actions |
|
|
|-----------------------|------------------|
|
|
| `organization_member` | `read` |
|
|
| `template` | `read`, `use` |
|
|
| `workspace` | `delete`, `read` |
|
|
| `workspace_secret` | `create` |
|
|
|
|
### `coder:workspaces.operate`
|
|
|
|
| Resource | Actions |
|
|
|-----------------------|-----------------------------------|
|
|
| `organization_member` | `read` |
|
|
| `template` | `read` |
|
|
| `workspace` | `read`, `start`, `stop`, `update` |
|
|
| `workspace_secret` | `create` |
|
|
|
|
## 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. |
|
|
|
|
### `organization_skill`
|
|
|
|
| Scope | Description |
|
|
|-----------------------------|----------------------------------------------------------------------------------|
|
|
| `organization_skill:*` | Every action on `organization_skill`, including actions not listed on this page. |
|
|
| `organization_skill:create` | Create an organization skill. |
|
|
| `organization_skill:delete` | Delete an organization skill. |
|
|
| `organization_skill:read` | Read organization skill metadata and content. |
|
|
| `organization_skill:share` | Share an organization skill with other users or groups. |
|
|
| `organization_skill:update` | Update an organization skill. |
|
|
|
|
### `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` |
|