mirror of
https://github.com/coder/coder.git
synced 2026-06-02 20:48:20 +00:00
Kacper Sawicki
1e274063d4
## Summary
Moves expired token filtering from client-side to server-side by adding
an `include_expired` parameter to the `GetAPIKeysByLoginType` and
`GetAPIKeysByUserID` database queries. This is more efficient for large
deployments with many expired/short-lived tokens.
## Changes
- Add `include_expired` parameter to SQL queries using `OR`
short-circuit
- Add `include_expired` query parameter to `GET
/users/{user}/keys/tokens`
- Add `IncludeExpired` field to `codersdk.TokensFilter`
- Remove client-side filtering from CLI `tokens list` command
- Add `TestTokensFilterExpired` test
Fixes coder/internal#1357
172 lines
5.5 KiB
Markdown
172 lines
5.5 KiB
Markdown
# API & Session Tokens
|
|
|
|
Users can generate tokens to make API requests on behalf of themselves.
|
|
|
|
## Short-Lived Tokens (Sessions)
|
|
|
|
The [Coder CLI](../../install/cli.md) and
|
|
[Backstage Plugin](https://github.com/coder/backstage-plugins) use short-lived
|
|
token to authenticate. To generate a short-lived session token on behalf of your
|
|
account, visit the following URL: `https://coder.example.com/cli-auth`
|
|
|
|
### Retrieve the current session token
|
|
|
|
If you're already logged in with the CLI, you can retrieve your current session
|
|
token for use in scripts and automation:
|
|
|
|
```sh
|
|
coder login token
|
|
```
|
|
|
|
This is useful for passing your session token to other tools:
|
|
|
|
```sh
|
|
export CODER_SESSION_TOKEN=$(coder login token)
|
|
```
|
|
|
|
### Session Durations
|
|
|
|
By default, sessions last 24 hours and are automatically refreshed. You can
|
|
configure
|
|
[`CODER_SESSION_DURATION`](../../reference/cli/server.md#--session-duration) to
|
|
change the duration and
|
|
[`CODER_DISABLE_SESSION_EXPIRY_REFRESH`](../../reference/cli/server.md#--disable-session-expiry-refresh)
|
|
to configure this behavior.
|
|
|
|
## Long-Lived Tokens (API Tokens)
|
|
|
|
Users can create long lived tokens. We refer to these as "API tokens" in the
|
|
product.
|
|
|
|
### Generate a long-lived API token on behalf of yourself
|
|
|
|
<div class="tabs">
|
|
|
|
#### UI
|
|
|
|
Visit your account settings in the top right of the dashboard or by navigating
|
|
to `https://coder.example.com/settings/account`
|
|
|
|
Navigate to the tokens page in the sidebar and create a new token:
|
|
|
|
|
|
|
|
#### CLI
|
|
|
|
Use the following command:
|
|
|
|
```sh
|
|
coder tokens create --name=my-token --lifetime=720h
|
|
```
|
|
|
|
See the help docs for
|
|
[`coder tokens create`](../../reference/cli/tokens_create.md) for more info.
|
|
|
|
</div>
|
|
|
|
### Generate a long-lived API token on behalf of another user
|
|
|
|
You must have the `Owner` role to generate a token for another user.
|
|
|
|
As of Coder v2.17+, you can use the CLI or API to create long-lived tokens on
|
|
behalf of other users. Use the API for earlier versions of Coder.
|
|
|
|
<div class="tabs">
|
|
|
|
#### CLI
|
|
|
|
```sh
|
|
coder tokens create --name my-token --user <username>
|
|
```
|
|
|
|
See the full CLI reference for
|
|
[`coder tokens create`](../../reference/cli/tokens_create.md)
|
|
|
|
#### API
|
|
|
|
Use our API reference for more information on how to
|
|
[create token API key](../../reference/api/users.md#create-token-api-key)
|
|
|
|
</div>
|
|
|
|
### Set max token length
|
|
|
|
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.
|
|
|
|
### Remove or expire a token
|
|
|
|
You can remove a token using the CLI or the API. By default, `coder tokens remove`
|
|
expires the token, (soft-delete):
|
|
|
|
```console
|
|
coder tokens remove <name|id>
|
|
```
|
|
|
|
Expired tokens can no longer be used for authentication and are hidden from
|
|
token listings by default. To include expired tokens, use the
|
|
`--include-expired` flag:
|
|
|
|
```console
|
|
coder tokens list --include-expired
|
|
```
|
|
|
|
To hard-delete a token, use the `--delete` flag:
|
|
|
|
```console
|
|
coder tokens remove --delete <name|id>
|
|
```
|
|
|
|
## 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
|
|
```
|