Refresh Token Flow

The Refresh Token grant (RFC 6749 §6) exchanges a long-lived refresh token for a new access token, keeping a user session alive without asking them to log in again every hour.

Token lifetimes & rotation

3SO defaults to a 1-hour access token TTL and a 30-day refresh token TTL, both configurable per deployment. Refresh Token Rotation — issuing a new refresh token on every use and invalidating the old one — is on the 3SO roadmap to further reduce the blast radius of a leaked refresh token.

1. Token Refresh Request

When the access token nears expiry, the client submits the refresh token it was issued alongside the original access token.

POST /oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&
refresh_token=GEbRxBN...edjnXbL&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET

2. New Token Pair

The server validates the refresh token and issues a fresh access token — and, with rotation enabled, a new refresh token as well.

{
  "access_token": "eyJz93a...NEW_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "NEW_REFRESH_TOKEN",
  "scope": "read write"
}