docs(upgrading): clarify ephemeral token revocation behavior

Ephemeral tokens (≤ MaxAccessTokenLifetime) skip store validation
and cannot be individually revoked until they expire.

commit: a98b865228b59c239fbf37911760b8b0f4044c17
author: brice · 7mo ago · 2026-03-22 06:54 UTC
committer: brice · 7mo ago · 2026-03-22 17:35 UTC
parent: a5ba9ca
signature: GPG VerifiedCD88F9E564E0102646FB6077A1A07C7C7C3E349D · arch-gpg Verified for the committer email

1 file · +7 -5

M docs/upgrading.md +7 -5


@@ -2,11 +2,11 @@
2	2
3	3		This guide covers breaking changes and migration steps between major versions.
4	4
5		-	## v2.7.0 to v2.8.0
	5	+	## v2.16.0 to v2.30.0
6	6
7	7		### Breaking: Password Authentication Removed
8	8
9		-	Gordon v2.8.0 removes password-based authentication entirely. Only token-based authentication is supported.
	9	+	Gordon v2.30.0 removes password-based authentication entirely. Only token-based authentication is supported.
10	10
11	11		What changed:
12	12

@@ -41,7 +41,7 @@ Gordon v2.8.0 removes password-based authentication entirely. Only token-based a
41	41
42	42		3. Update your config to remove password fields:
43	43
44		-	Before (v2.7.0):
	44	+	Before (v2.16.0):
45	45		```toml
46	46		[auth]
47	47		enabled = true

@@ -51,7 +51,7 @@ Gordon v2.8.0 removes password-based authentication entirely. Only token-based a
51	51		token_secret = "gordon/auth/token_secret"
52	52		```
53	53
54		-	After (v2.8.0):
	54	+	After (v2.30.0):
55	55		```toml
56	56		[auth]
57	57		enabled = true

@@ -77,7 +77,9 @@ Gordon v2.8.0 removes password-based authentication entirely. Only token-based a
77	77
78	78		### New: Configurable Access Token TTL
79	79
80		-	Ephemeral access tokens issued by `/auth/token` now have a configurable lifetime via `auth.access_token_ttl`. The default is `"15m"`. Tokens with a lifetime of 1 hour or less skip store validation for performance.
	80	+	Ephemeral access tokens issued by `/auth/token` now have a configurable lifetime via `auth.access_token_ttl` (default `"15m"`, maximum `"1h"`).
	81	+
	82	+	Tokens with a lifetime at or below `MaxAccessTokenLifetime` (1 hour) are treated as ephemeral: they skip token store validation for performance, which means they cannot be individually revoked. They become invalid only when they naturally expire. If you need tighter revocation control, use a shorter TTL.
81	83
82	84		```toml
83	85		[auth]

 This guide covers breaking changes and migration steps between major versions.
-## v2.7.0 to v2.8.0
+## v2.16.0 to v2.30.0
 ### Breaking: Password Authentication Removed
-Gordon v2.8.0 removes password-based authentication entirely. Only token-based authentication is supported.
+Gordon v2.30.0 removes password-based authentication entirely. Only token-based authentication is supported.
 **What changed:**
 3. **Update your config** to remove password fields:
-   **Before (v2.7.0):**
+   **Before (v2.16.0):**
    ```toml
    [auth]
    enabled = true
    token_secret = "gordon/auth/token_secret"
    ```
-   **After (v2.8.0):**
+   **After (v2.30.0):**
    ```toml
    [auth]
    enabled = true
 ### New: Configurable Access Token TTL
-Ephemeral access tokens issued by `/auth/token` now have a configurable lifetime via `auth.access_token_ttl`. The default is `"15m"`. Tokens with a lifetime of 1 hour or less skip store validation for performance.
+Ephemeral access tokens issued by `/auth/token` now have a configurable lifetime via `auth.access_token_ttl` (default `"15m"`, maximum `"1h"`).
+Tokens with a lifetime at or below `MaxAccessTokenLifetime` (1 hour) are treated as ephemeral: they skip token store validation for performance, which means they **cannot be individually revoked**. They become invalid only when they naturally expire. If you need tighter revocation control, use a shorter TTL.
 ```toml
 [auth]