Refresh expired access tokens using the stored refresh token

resolve_token now redeems the persisted refresh_token via the OAuth2 refresh_token grant when the stored access token is expired or within a short skew window, then writes the new token back to the keyring. It falls back to the previous AUTH_TOKEN_EXPIRED behaviour only when no refresh token is available or the refresh is rejected. resolve_token is now async, so all call sites await it.

Author: amanjoshicodes

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/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/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:

src/auth/mod.rs

@@ -2,16 +2,25 @@ pub mod auth_code_pkce;
 pub mod client_credentials;
 pub mod device_code;
 pub mod keyring;
+pub mod refresh;
 pub mod token;
 
+use chrono::{Duration, Utc};
+
+use crate::config::DEFAULT_DELEGATED_SCOPES;
 use crate::error::{Result, TeamsError};
 use token::TokenInfo;
 
+/// Refresh slightly ahead of the hard expiry so a token does not lapse
+/// mid-request.
+const EXPIRY_SKEW_SECS: i64 = 60;
+
 /// Resolve an access token using the priority chain:
-/// 1. TEAMS_CLI_ACCESS_TOKEN env var
-/// 2. Keyring (stored token, check expiry)
+/// 1. TEAMS_CLI_ACCESS_TOKEN env var (used verbatim, never refreshed)
+/// 2. Keyring: if the stored token is (near) expired, silently redeem its
+///    refresh token; otherwise return it as-is
 /// 3. Error
-pub fn resolve_token(profile: &str) -> Result<TokenInfo> {
+pub async fn resolve_token(profile: &str) -> Result<TokenInfo> {
     // 1. Direct env var override
     if let Ok(token) = std::env::var("TEAMS_CLI_ACCESS_TOKEN") {
         return Ok(TokenInfo {
@@ -27,10 +36,18 @@ pub fn resolve_token(profile: &str) -> Result<TokenInfo> {
     // 2. Keyring
     match keyring::get_token(profile) {
         Ok(info) => {
-            if info.is_expired() {
-                Err(TeamsError::TokenExpired)
-            } else {
-                Ok(info)
+            if !needs_refresh(&info) {
+                return Ok(info);
+            }
+            // Token is at/near expiry: attempt a silent refresh-token
+            // redemption. Any failure falls back to the original behaviour
+            // (TokenExpired) so the observable exit code is unchanged.
+            match attempt_refresh(profile, &info).await {
+                Ok(refreshed) => Ok(refreshed),
+                Err(e) => {
+                    tracing::debug!("Silent token refresh failed, treating as expired: {e}");
+                    Err(TeamsError::TokenExpired)
+                }
             }
         }
         Err(_) => Err(TeamsError::AuthError(
@@ -39,6 +56,63 @@ pub fn resolve_token(profile: &str) -> Result<TokenInfo> {
     }
 }
 
+/// Whether the token should be refreshed: already expired, or within the skew
+/// window of expiry. Tokens with no expiry information are assumed valid.
+fn needs_refresh(info: &TokenInfo) -> bool {
+    info.is_expired()
+        || matches!(
+            info.expires_at,
+            Some(expires) if Utc::now() + Duration::seconds(EXPIRY_SKEW_SECS) >= expires
+        )
+}
+
+/// Silently redeem the stored refresh token for a fresh access token and persist
+/// it. Returns an error (mapped to `TokenExpired` by the caller) when the token
+/// cannot be refreshed — e.g. no refresh token, undecodable claims, or the
+/// identity platform rejecting the request.
+async fn attempt_refresh(profile: &str, info: &TokenInfo) -> Result<TokenInfo> {
+    let refresh_token = info
+        .refresh_token
+        .as_deref()
+        .ok_or(TeamsError::TokenExpired)?;
+
+    // The expired JWT still decodes (decoding ignores expiry); recover the
+    // tenant + client id originally authenticated with from its claims.
+    let claims = info.unverified_claims().ok_or(TeamsError::TokenExpired)?;
+    let tenant_id = claims.tid.ok_or(TeamsError::TokenExpired)?;
+    let client_id = claims
+        .azp
+        .or(claims.appid)
+        .ok_or(TeamsError::TokenExpired)?;
+
+    let scope = refresh_scope(info.scope.as_deref());
+
+    let response =
+        refresh::refresh_access_token(&client_id, &tenant_id, refresh_token, &scope).await?;
+    let refreshed = response.into_token_info(profile);
+
+    // Best-effort persistence so the next invocation reuses the new token.
+    let _ = keyring::store_token(profile, &refreshed);
+
+    Ok(refreshed)
+}
+
+/// Build the scope string for the refresh request: reuse the originally granted
+/// scope (ensuring `offline_access` so future refreshes keep working), or fall
+/// back to the default delegated scopes.
+fn refresh_scope(existing: Option<&str>) -> String {
+    match existing {
+        Some(scope) if !scope.trim().is_empty() => {
+            if scope.split_whitespace().any(|s| s == "offline_access") {
+                scope.to_string()
+            } else {
+                format!("{scope} offline_access")
+            }
+        }
+        _ => DEFAULT_DELEGATED_SCOPES.to_string(),
+    }
+}
+
 pub fn require_delegated_token(token: &TokenInfo, operation: &str) -> Result<()> {
     if let Some(claims) = token.unverified_claims() {
         if claims.auth_type() == "app-only" {
@@ -50,3 +124,92 @@ pub fn require_delegated_token(token: &TokenInfo, operation: &str) -> Result<()>
 
     Ok(())
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn token_with(
+        expires_at: Option<chrono::DateTime<Utc>>,
+        refresh_token: Option<&str>,
+        scope: Option<&str>,
+    ) -> TokenInfo {
+        TokenInfo {
+            access_token: "not-a-jwt".into(),
+            expires_at,
+            token_type: "Bearer".into(),
+            scope: scope.map(|s| s.to_string()),
+            refresh_token: refresh_token.map(|s| s.to_string()),
+            profile: "default".into(),
+        }
+    }
+
+    #[test]
+    fn needs_refresh_true_when_expired() {
+        let info = token_with(Some(Utc::now() - Duration::hours(1)), None, None);
+        assert!(needs_refresh(&info));
+    }
+
+    #[test]
+    fn needs_refresh_true_within_skew_window() {
+        // Expires in 30s, which is inside the 60s skew window.
+        let info = token_with(Some(Utc::now() + Duration::seconds(30)), None, None);
+        assert!(needs_refresh(&info));
+    }
+
+    #[test]
+    fn needs_refresh_false_when_well_in_future() {
+        let info = token_with(Some(Utc::now() + Duration::hours(1)), None, None);
+        assert!(!needs_refresh(&info));
+    }
+
+    #[test]
+    fn needs_refresh_false_without_expiry() {
+        let info = token_with(None, None, None);
+        assert!(!needs_refresh(&info));
+    }
+
+    #[test]
+    fn refresh_scope_falls_back_to_defaults_when_absent() {
+        assert_eq!(refresh_scope(None), DEFAULT_DELEGATED_SCOPES);
+        assert_eq!(refresh_scope(Some("   ")), DEFAULT_DELEGATED_SCOPES);
+    }
+
+    #[test]
+    fn refresh_scope_appends_offline_access_when_missing() {
+        assert_eq!(
+            refresh_scope(Some("User.Read Chat.ReadWrite")),
+            "User.Read Chat.ReadWrite offline_access"
+        );
+    }
+
+    #[test]
+    fn refresh_scope_preserves_existing_offline_access() {
+        assert_eq!(
+            refresh_scope(Some("User.Read offline_access")),
+            "User.Read offline_access"
+        );
+    }
+
+    #[tokio::test]
+    async fn attempt_refresh_without_refresh_token_is_token_expired() {
+        // Expired token, no refresh token: must fail fast as TokenExpired with
+        // no network call.
+        let info = token_with(Some(Utc::now() - Duration::hours(1)), None, None);
+        let err = attempt_refresh("default", &info).await.unwrap_err();
+        assert!(matches!(err, TeamsError::TokenExpired));
+    }
+
+    #[tokio::test]
+    async fn attempt_refresh_with_undecodable_claims_is_token_expired() {
+        // Has a refresh token, but the access token is not a decodable JWT so we
+        // cannot recover tenant/client id: must fail fast as TokenExpired.
+        let info = token_with(
+            Some(Utc::now() - Duration::hours(1)),
+            Some("a-refresh-token"),
+            None,
+        );
+        let err = attempt_refresh("default", &info).await.unwrap_err();
+        assert!(matches!(err, TeamsError::TokenExpired));
+    }
+}

src/auth/refresh.rs

@@ -0,0 +1,43 @@
+use reqwest::Client;
+
+use super::token::MsTokenResponse;
+use crate::error::{Result, TeamsError};
+
+/// Redeem a stored refresh token for a fresh access token using the OAuth2
+/// `refresh_token` grant against the Microsoft identity platform.
+///
+/// Mirrors the error handling of [`super::device_code::authenticate`]: network
+/// failures surface as [`TeamsError::NetworkError`], non-2xx responses and parse
+/// failures as [`TeamsError::AuthError`].
+pub async fn refresh_access_token(
+    client_id: &str,
+    tenant_id: &str,
+    refresh_token: &str,
+    scope: &str,
+) -> Result<MsTokenResponse> {
+    let token_url = format!("https://login.microsoftonline.com/{tenant_id}/oauth2/v2.0/token");
+    let http = Client::new();
+
+    let resp = http
+        .post(&token_url)
+        .form(&[
+            ("grant_type", "refresh_token"),
+            ("client_id", client_id),
+            ("refresh_token", refresh_token),
+            ("scope", scope),
+        ])
+        .send()
+        .await
+        .map_err(TeamsError::NetworkError)?;
+
+    if !resp.status().is_success() {
+        let body = resp.text().await.unwrap_or_default();
+        return Err(TeamsError::AuthError(format!(
+            "Token refresh failed: {body}"
+        )));
+    }
+
+    resp.json::<MsTokenResponse>()
+        .await
+        .map_err(|e| TeamsError::AuthError(format!("Failed to parse refresh response: {e}")))
+}

src/cli/app.rs

@@ -40,7 +40,7 @@ pub async fn run(
     format: OutputFormat,
     pagination: &PaginationOpts,
 ) -> Result<()> {
-    let token = auth::resolve_token(profile)?;
+    let token = auth::resolve_token(profile).await?;
     let client = GraphClient::new(token, &config.network)?;
 
     match cmd {

src/cli/auth.rs

@@ -242,7 +242,7 @@ pub async fn run(
                 "byo"
             };
 
-            let token = auth::resolve_token(profile).ok();
+            let token = auth::resolve_token(profile).await.ok();
             let claims = token.as_ref().and_then(|t| t.unverified_claims());
             let warnings = token_warnings(claims.as_ref());
             let admin_consent_url = delegated_admin_consent_url(&client_id, &tenant_id);
@@ -273,7 +273,7 @@ pub async fn run(
 
         AuthCommand::Status => {
             let start = Instant::now();
-            match auth::resolve_token(profile) {
+            match auth::resolve_token(profile).await {
                 Ok(token) => {
                     let claims = token.unverified_claims();
                     let msg = serde_json::json!({
@@ -312,7 +312,7 @@ pub async fn run(
         AuthCommand::Switch { name } => {
             let start = Instant::now();
             // Verify the profile has a token
-            auth::resolve_token(&name)?;
+            auth::resolve_token(&name).await?;
 
             // Update config to set default profile
             let mut updated_config = config.clone();
@@ -359,7 +359,7 @@ pub async fn run(
         AuthCommand::Token {
             format: token_format,
         } => {
-            let token = auth::resolve_token(profile)?;
+            let token = auth::resolve_token(profile).await?;
             match token_format.as_str() {
                 "json" => {
                     let claims = token.unverified_claims();

src/cli/channel.rs

@@ -104,7 +104,7 @@ pub async fn run(
     format: OutputFormat,
     pagination: &PaginationOpts,
 ) -> Result<()> {
-    let token = auth::resolve_token(profile)?;
+    let token = auth::resolve_token(profile).await?;
     let client = GraphClient::new(token, &config.network)?;
 
     match cmd {

src/cli/chat.rs

@@ -95,7 +95,7 @@ pub async fn run(
     format: OutputFormat,
     pagination: &PaginationOpts,
 ) -> Result<()> {
-    let token = auth::resolve_token(profile)?;
+    let token = auth::resolve_token(profile).await?;
     let client = GraphClient::new(token, &config.network)?;
 
     match cmd {

src/cli/file.rs

@@ -103,7 +103,7 @@ pub async fn run(
     format: OutputFormat,
     pagination: &PaginationOpts,
 ) -> Result<()> {
-    let token = auth::resolve_token(profile)?;
+    let token = auth::resolve_token(profile).await?;
     let client = GraphClient::new(token, &config.network)?;
 
     match cmd {