Refresh expired access tokens using the stored refresh token

Refresh expired access tokens using the stored refresh token

Author: sionsmith

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## Unreleased
+
+### Added
+
+- Automatic refresh-token redemption. When the stored access token is expired (or within a short skew window of expiring), the CLI now silently exchanges the persisted `refresh_token` for a fresh access token via the OAuth2 `refresh_token` grant and updates the keyring, instead of failing with `AUTH_TOKEN_EXPIRED` roughly an hour after login. The previous re-login behaviour remains as a fallback when no refresh token is stored or the refresh request is rejected. This resolves the standing "automatic refresh-token handling" known limitation (#16).
+
 ## v0.2.4 - 2026-06-04
 
 ### Changed

docs/auth.md

@@ -194,7 +194,7 @@ Tokens are stored in the operating system keyring:
 
 The config file stores profile settings, not access tokens.
 
-Current known gap: automatic refresh-token handling is not yet release-grade. If a token expires and refresh does not happen, commands return `AUTH_TOKEN_EXPIRED` and the user must run `teams auth login` again.
+The CLI automatically redeems the stored refresh token when an access token is expired or near expiry, then updates the keyring with the refreshed token. If no refresh token is stored, or the identity platform rejects the refresh request, commands return `AUTH_TOKEN_EXPIRED` and the user must run `teams auth login` again.
 
 ## Diagnostics
 

docs/faq.md

@@ -63,7 +63,7 @@ Teams/Graph can list chats that later fail message reads because the user is no
 
 ## Why did I get `AUTH_TOKEN_EXPIRED`?
 
-The stored access token expired. The CLI requests `offline_access`, but automatic refresh-token handling is still a release-readiness gap. Run:
+The CLI automatically refreshes an expired access token using the stored refresh token (login requests `offline_access`), so this should be rare. You will still see `AUTH_TOKEN_EXPIRED` when no refresh token is stored or the refresh is rejected — for example the refresh token itself expired or was revoked. In that case, re-authenticate:
 
 ```bash
 teams auth login --device-code

docs/man/teams-auth.7

@@ -122,8 +122,9 @@ Tenant ID or tenant domain.
 Test-only switch used to avoid OS keyring access in automated tests. Do not use
 for real login sessions.
 .SH KNOWN GAPS
-Automatic refresh-token handling must be completed and validated before public
-commercial release. If a stored access token expires today, run:
+Stored access tokens are refreshed automatically when a refresh token is
+available. If the refresh token is missing, expired, revoked, or rejected by
+the identity platform, run:
 .PP
 .nf
 teams auth login --device-code

docs/release-readiness.md

@@ -29,7 +29,7 @@ Live read-only validation passed against the OSO profile:
 Known live behavior:
 
 - Some meeting chats can appear in `chat list` but reject message reads with `403` if the user is no longer in the roster.
-- Stored token expiry currently requires manual re-login.
+- Stored token expiry is handled through refresh-token redemption when a refresh token is available. `AUTH_TOKEN_EXPIRED` still means the refresh token is missing, expired, revoked, or rejected by the identity platform.
 
 Entra app registration status as of 2026-05-27:
 
@@ -120,15 +120,14 @@ Dependabot is configured to group GitHub Actions updates into one PR so the comp
 These must be resolved before marketing this as production-ready for external customers:
 
 1. Publisher verification for the OSO Entra app.
-2. Automatic refresh-token handling and tests.
-3. Windows live validation using Windows Credential Manager.
-4. Controlled write/read smoke test in a dedicated Teams test channel.
-5. Documented admin-consent onboarding flow for customer tenants.
-6. Clear policy for unsupported Graph operations, tenant restrictions, and destructive commands.
-7. Security review of token storage, logs, and exported token behavior.
-8. Versioned release notes and upgrade guidance.
-9. Public website HTTPS fixed for `https://msteamscli.com/`; HTTP is live, but the current TLS certificate does not cover the hostname.
-10. Terms of service URL published and added to the Entra app branding.
+2. Windows live validation using Windows Credential Manager.
+3. Controlled write/read smoke test in a dedicated Teams test channel.
+4. Documented admin-consent onboarding flow for customer tenants.
+5. Clear policy for unsupported Graph operations, tenant restrictions, and destructive commands.
+6. Security review of token storage, logs, and exported token behavior.
+7. Versioned release notes and upgrade guidance.
+8. Public website HTTPS fixed for `https://msteamscli.com/`; HTTP is live, but the current TLS certificate does not cover the hostname.
+9. Terms of service URL published and added to the Entra app branding.
 
 ## Microsoft official trust checklist
 

docs/troubleshooting.md

@@ -18,16 +18,16 @@ RUST_LOG=teams=debug teams chat list --output json
 
 ## `AUTH_TOKEN_EXPIRED`
 
-Meaning: the keyring token is expired.
+Meaning: the keyring access token is expired and could not be refreshed automatically.
 
-Current workaround:
+The CLI now silently redeems the stored refresh token when the access token is expired or about to expire, so this error normally only appears when no refresh token is stored or the refresh request is rejected (for example the refresh token expired or was revoked).
+
+Resolution:
 
 ```bash
 teams auth login --device-code
 ```
 
-Release-readiness note: automatic refresh-token handling still needs to be completed and validated.
-
 ## `AUTH_FAILED` or login fails
 
 Check: