Troubleshooting Token Expiration

Symptoms

• Sudden 401 errors after a period of use
• "Token expired" error messages
• Being logged out unexpectedly

Understanding Token Lifetimes

Token	Lifetime	Action on Expiry
Access token	1 hour	Auto-refreshed by the app
Refresh token	30 days	Requires re-login

Solutions

Webapp: Auto-Refresh Not Working

If you're getting 401 errors in the webapp:

1. Hard refresh the page (Ctrl+Shift+R / Cmd+Shift+R)
2. Clear local storage: DevTools > Application > Local Storage > Clear
3. Log out and log in again

CLI: Token Expired

# Check current auth status
surestage auth status

# Manually refresh
surestage auth refresh

# If refresh fails, re-login
surestage auth login

API: Handling Token Refresh

Implement automatic token refresh in your integration:

// When you get a 401 response
if (response.status === 401) {
  const newTokens = await fetch('/auth/refresh', {
    method: 'POST',
    body: JSON.stringify({ refreshToken }),
  });
  // Retry the original request with the new access token
}