OAuth2 Refresh Token

OAuth2 Refresh Token is a long-lived credential used to obtain new access tokens without requiring the user to re-authenticate. This enables persistent sessions while keeping access tokens short-lived for security.

How It Works

// Initial token response includes refresh token
{
  "access_token": "short_lived_token",
  "expires_in": 3600,
  "refresh_token": "long_lived_refresh"
}

// When access token expires, use refresh token
POST /token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&
refresh_token=long_lived_refresh&
client_id=app123&
client_secret=secret

// Response: new access token
{
  "access_token": "new_short_lived_token",
  "expires_in": 3600,
  "refresh_token": "new_or_same_refresh"  // may rotate
}

Security Considerations

  • Store securely (server-side preferred, encrypted if client-side)
  • Never expose to JavaScript in browser (use HttpOnly cookie)
  • Implement refresh token rotation (issue new refresh token each use)
  • Detect and revoke on reuse (token replay detection)
  • Bind to client credentials

Refresh Token Rotation

// If old refresh token is reused after rotation:
// 1. Detected as potential theft
// 2. Revoke all tokens for that grant
// 3. Force re-authentication

See Also