Skip to content

Docs: Document token lifecycle, capping mechanisms, and default TTLs#377

Merged
teemow merged 1 commit intomainfrom
docs/token-lifecycle-documentation
Feb 23, 2026
Merged

Docs: Document token lifecycle, capping mechanisms, and default TTLs#377
teemow merged 1 commit intomainfrom
docs/token-lifecycle-documentation

Conversation

@teemow
Copy link
Member

@teemow teemow commented Feb 23, 2026

Summary

  • Expands docs/operations/security.md from a stub into a comprehensive token lifecycle guide covering the dual token loop (agent-muster and muster-Dex), access token capping via capTokenExpiry, refresh token alignment with Dex's absoluteLifetime, and all default TTL values
  • Adds an Access Token TTL section to docs/reference/configuration.md explaining the capping mechanism and clarifies the rolling-vs-absolute distinction in the session duration warning
  • Improves the Token Expired troubleshooting section in docs/reference/cli/auth.md with explanations of what "Expires" and "Session" mean, and cross-references to the new security guide

Context

Analysis of the token lifecycle (see token TTL analysis plan) identified that while the code correctly aligns muster's default TTLs with Dex (30m access tokens, 30d session duration), the documentation didn't explain the capping mechanism, the dual token loop, or the default values. The existing docs warned about the rolling-vs-absolute mismatch but treated it purely as a configuration concern without explaining the underlying architecture.

Test plan

  • Verify all cross-references between the three updated docs resolve correctly
  • Verify mermaid diagram renders in GitHub markdown preview

Made with Cursor

Adds comprehensive token lifecycle documentation covering the dual token
loop between muster and Dex, access token capping via capTokenExpiry,
refresh token alignment with Dex's absoluteLifetime, and default TTL
values. Updates security operations guide, configuration reference, and
CLI auth reference with cross-references.

Co-authored-by: Cursor <cursoragent@cursor.com>
@teemow teemow requested a review from a team as a code owner February 23, 2026 00:04
@teemow teemow merged commit 44ca19a into main Feb 23, 2026
7 checks passed
@teemow teemow deleted the docs/token-lifecycle-documentation branch February 23, 2026 00:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant