Tokens and sessions

Short-lived access tokens, ID tokens that say who signed in, and rotating refresh tokens to keep players signed in.

TokenFormatLifetimeUse
Access tokenJWT, RS256, typ at+jwt1 hourBearer token for the Social API and userinfo.
ID tokenJWT, RS2561 hourWho signed in. Read it once at sign-in.
Refresh tokenOpaque (rrt_…)60 days, rotated on every useGet new tokens without asking the player. Only with offline_access.

Refreshing

bash
curl -X POST https://api.reanstudios.com/api/oauth/token \
  -d grant_type=refresh_token \
  -d refresh_token=rrt_… \
  -d client_id=rean_xxxxxxxxxxxxxxxxxxxxxxxx
  • Every refresh returns a new refresh token. Store it and throw the old one away.
  • Using an old refresh token again revokes the whole chain (it means the token was copied). The player has to sign in again.
  • You may narrow the scopes on refresh (scope=openid), never widen them.
  • All SDKs refresh automatically a minute before the access token expires, and once after a 401.

Access token claims

json
{
  "iss": "https://api.reanstudios.com",
  "sub": "4f9c2b1e-7a3d-4c55-9e10-2f6b8a1d3c77",
  "aud": "rean_xxxxxxxxxxxxxxxxxxxxxxxx",
  "client_id": "rean_xxxxxxxxxxxxxxxxxxxxxxxx",
  "scope": "openid profile friends.read",
  "iat": 1795420800,
  "exp": 1795424400,
  "jti": "0b7f…"
}

Treat access tokens as opaque in your game; only REAN's API needs to read them.

Signing out and revocation

POSThttps://api.reanstudios.com/api/oauth/revokeRFC 7009

Send the refresh token when the player signs out of your game; its whole chain stops working. The endpoint always answers 200.

Players can also remove your app in Account › Connected apps on reanstudios.com. That ends all of your tokens for that player at once, access tokens included: your next API call gets 401 invalid_token, and the SDKs sign the player out.