feat(cli)!: expire tokens by default by johnstcn · Pull Request #21783 · coder/coder

johnstcn · 2026-01-30T10:43:33Z

Summary

NOTE: Calling this out as a breaking change in case existing consumers of the CLI depend on being able to see expired tokens OR being able to delete tokens immediately.

Updates the coder tokens rm command to immediately expire a token by ID, preserving the token record for audit trail purposes. Tokens can still be deleted by passing --delete.

Problem

During an incident on dev.coder.com, operators needed to urgently expire an API key that was stuck in a hot loop. The only way to do this was via direct database access:

UPDATE api_keys SET expires_at = NOW() WHERE id = '...';

This is not ideal for operators who may not have direct DB access or want to avoid manual SQL.

Solution

This PR adds:

API endpoint: PUT /api/v2/users/{user}/keys/{keyid}/expire - Sets the token's expires_at to now
SDK method: ExpireAPIKey(ctx, userID, keyID)
Updates CLI: coder tokens rm <name|id|token> now expires by default. You can still delete by passing the --delete flag. The coder tokens list command now also hides expired tokens by default. You can --include-expired if needed to include them.
Audit logging: The expire action is logged with old and new key states

Test plan

Tests cover: owner expiring own token, admin expiring other user's token, non-admin cannot expire other's token, 404 for non-existent token

Closes #21782

🤖 Generated with Claude Code

This adds a new `coder tokens expire` command that allows admins/owners to immediately expire a token by ID. Unlike `coder tokens rm` which deletes the token entirely, this preserves the token record for audit trail purposes. This is useful during incident response when a token needs to be urgently revoked without direct database access. The implementation includes: - New API endpoint: PUT /api/v2/users/{user}/keys/{keyid}/expire - New SDK method: ExpireAPIKey - New CLI command: coder tokens expire <name|id|token> - Audit logging for the expire action Closes #21782 Co-Authored-By: Claude Opus 4.5 <[email protected]>

deansheather · 2026-02-03T09:30:10Z

Why not just use coder tokens remove? If the expiry functionality is what you specifically want for auditing puposes, why not change that endpoint to expire instead of delete?

johnstcn · 2026-02-03T11:20:22Z

Why not just use coder tokens remove? If the expiry functionality is what you specifically want for auditing puposes, why not change that endpoint to expire instead of delete?

Good point - dbpurge will automatically delete API keys expired for a certain threshold. The only worry I'd have here is that users will complain about seeing expired API keys in the CLI output, which is a temporary state anyway (7 days by default).

deansheather · 2026-02-03T13:01:15Z

Could control it with a flag, perhaps by default? IDM, but I don't think we should have two commands that are almost identical in function

johnstcn · 2026-02-03T13:07:17Z

Could control it with a flag, perhaps by default? IDM, but I don't think we should have two commands that are almost identical in function

Something like coder tokens delete --expire=false my-token?

deansheather · 2026-02-04T02:37:28Z

If the default behavior of remove becomes expiry, maybe --force
Otherwise, --expire=true

This changes the default behavior of `coder tokens remove` to expire tokens instead of deleting them, preserving the audit trail. Use `--delete` to permanently delete a token. Changes: - Default behavior now expires tokens (preserves audit trail) - Add `--delete` flag for permanent deletion - Add `--include-expired` flag to `tokens ls` to show expired tokens - Add PUT /users/{user}/keys/{keyid}/expire API endpoint - Add ExpireAPIKey SDK method Breaking change: Scripts using `coder tokens remove` will now expire tokens instead of deleting them. Update to `coder tokens remove --delete` for the previous behavior.

docs/admin/users/sessions-tokens.md

cli/tokens.go

deansheather · 2026-02-17T03:15:45Z

docs/admin/users/sessions-tokens.md

+### Remove or expire a token
+
+You can remove a token using the CLI or the API. By default, `coder tokens remove`
+


Suggested change

docs/admin/users/sessions-tokens.md

dannykopping

LGTM 👍 a few minor comments

cli/tokens.go

dannykopping · 2026-02-17T07:14:56Z

cli/tokens.go

 	cmd := &serpent.Command{
 		Use:     "remove <name|id|token>",
 		Aliases: []string{"delete"},
 		Short:   "Delete a token",


The short description is stale.

cli/tokens.go

coderd/apikey.go

coderd/apikey_test.go

dannykopping · 2026-02-17T07:26:22Z

coderd/apikey_test.go

+			Lifetime: time.Hour * 24 * 7,
+		})
+		require.NoError(t, err)
+		keyID := strings.Split(res.Key, "-")[0]


Not something for this PR, but it bugs me that we don't have a parser for our API key format. We should be hiding this implementation detail behind a method on the Key.

coderd/apikey_test.go

coder-tasks · 2026-02-17T09:47:05Z

Documentation Check

Updates Needed

docs/admin/users/sessions-tokens.md - Incorrect statement about expired token visibility
⚠️ Lines 108-109 are incorrect: The documentation currently states "Expired tokens can no longer be used for authentication but remain visible in token listings." However, the actual behavior is that expired tokens are hidden by default in coder tokens list unless you pass --include-expired.

Suggested fix: Change lines 108-109 to:
```
Expired tokens can no longer be used for authentication and are hidden by default
in token listings. Use `coder tokens list --include-expired` to view expired tokens.
```

Previously Completed

Section "Remove or expire a token" added explaining the default expire behavior and --delete flag
CLI reference auto-generated for tokens_remove.md documenting --delete flag and new default behavior
CLI reference auto-generated for tokens_list.md documenting --include-expired flag
API reference documents the PUT /users/{user}/keys/{keyid}/expire endpoint
Audit logs documentation updated (auto-generated)

Summary

The documentation has been mostly updated, but contains an inaccuracy about expired token visibility that contradicts the actual CLI behavior (expired tokens are hidden by default, not visible).

Automated review via Coder Tasks

dannykopping · 2026-02-17T09:51:24Z

cli/testdata/coder_tokens_remove_--help.golden

  Aliases: delete, rm

+  Remove a token by expiring it. Use --delete to permanently delete the token
+  instead, which removes the audit trail.


Might be stale?

yep forgot to make gen

github-actions bot assigned johnstcn Jan 30, 2026

johnstcn force-pushed the feat/tokens-expire-command branch from 58aa3ec to 42b4846 Compare January 30, 2026 14:20

johnstcn added 2 commits February 3, 2026 08:35

Merge branch 'main' into feat/tokens-expire-command

9561e88

Merge branch 'main' into feat/tokens-expire-command

7e3b991

johnstcn marked this pull request as ready for review February 3, 2026 09:28

johnstcn requested review from Copilot, dannykopping and deansheather February 3, 2026 09:28

Copilot started reviewing on behalf of johnstcn February 3, 2026 09:29 View session

This comment was marked as duplicate.

Sign in to view

johnstcn added 2 commits February 3, 2026 11:10

chore: consolidate tests

a350e0d

fix: expire token in tx

7df49dc

This comment was marked as duplicate.

Sign in to view

deansheather removed their request for review February 4, 2026 13:05

johnstcn marked this pull request as draft February 9, 2026 09:17

johnstcn added 6 commits February 13, 2026 21:18

Merge branch 'main' into feat/tokens-expire-command

356e672

fix(cli): merge tokens expire into tokens remove --expire flag

3689536

fix(cli): address review feedback on tokens remove

3d4b27c

fix test after steven's recent changes

5d90307

appease linter

0529f61

Merge branch 'main' into feat/tokens-expire-command

0e730a6

johnstcn marked this pull request as ready for review February 16, 2026 09:24

johnstcn requested a review from deansheather February 16, 2026 09:25

Merge branch 'main' into feat/tokens-expire-command

b398f0a

This comment was marked as duplicate.

Sign in to view

johnstcn added 2 commits February 16, 2026 17:15

test(coderd): add DeletingExpiredTokenSucceeds test case

81b6343

johnstcn changed the title ~~feat(cli): add coder tokens expire command~~ feat(cli)!: expire tokens by default Feb 16, 2026

github-actions bot added the release/breaking This label is applied to PRs to detect breaking changes as part of the release process label Feb 16, 2026

Merge branch 'main' into feat/tokens-expire-command

5ccb067

This comment was marked as outdated.

Sign in to view

johnstcn commented Feb 16, 2026

View reviewed changes

docs/admin/users/sessions-tokens.md Outdated Show resolved Hide resolved

remove merge conflict marker

a07dec8

deansheather approved these changes Feb 17, 2026

View reviewed changes

dannykopping approved these changes Feb 17, 2026

View reviewed changes

address PR comments

da9babb

johnstcn mentioned this pull request Feb 17, 2026

Add the capability to filter API tokens server-side coder/internal#1357

Closed

dannykopping reviewed Feb 17, 2026

View reviewed changes

dannykopping approved these changes Feb 17, 2026

View reviewed changes

johnstcn added 2 commits February 17, 2026 12:17

fixup! address PR comments

8488155

gen harder

47cf2a9

johnstcn merged commit 4a3304f into main Feb 17, 2026
29 checks passed

johnstcn deleted the feat/tokens-expire-command branch February 17, 2026 13:16

github-actions bot locked and limited conversation to collaborators Feb 17, 2026

		### Remove or expire a token

		You can remove a token using the CLI or the API. By default, `coder tokens remove`

Conversation

johnstcn commented Jan 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Problem

Solution

Test plan

Uh oh!

deansheather commented Feb 3, 2026

Uh oh!

This comment was marked as duplicate.

This comment was marked as duplicate.

Uh oh!

This comment was marked as duplicate.

Uh oh!

This comment was marked as duplicate.

johnstcn commented Feb 3, 2026

Uh oh!

deansheather commented Feb 3, 2026

Uh oh!

johnstcn commented Feb 3, 2026

Uh oh!

deansheather commented Feb 4, 2026

Uh oh!

This comment was marked as duplicate.

This comment was marked as outdated.

Uh oh!

Uh oh!

deansheather Feb 17, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

dannykopping left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

dannykopping Feb 17, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dannykopping Feb 17, 2026

Choose a reason for hiding this comment

Uh oh!

johnstcn Feb 17, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

coder-tasks bot commented Feb 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation Check

Updates Needed

Previously Completed

Summary

Uh oh!

dannykopping Feb 17, 2026

Choose a reason for hiding this comment

Uh oh!

johnstcn Feb 17, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

johnstcn commented Jan 30, 2026 •

edited

Loading

coder-tasks bot commented Feb 17, 2026 •

edited

Loading