OIDC tokens and refresh

Lifetimes

Token	Lifetime
Access token	1 hour
ID token	1 hour
Refresh token	7 days, renewed at each refresh
Grant (the sign-in itself)	Expires after 30 days without use, extended on each use
Browser session on the provider	30 days
Sign-in page (login and consent)	1 hour

As long as your application refreshes at least once every 7 days, the member stays signed in without a new login.

Getting a refresh token

All three conditions are needed:

1. your client has the refresh_token grant;
2. offline_access is in the requested scope;
3. the authorization request carries prompt=consent.

Caution

Without prompt=consent, offline_access is silently dropped: the token response has no refresh_token, and no error tells you why.

Refresh token rotation

Refresh tokens are always rotated: each refresh returns a new refresh_token and invalidates the one you sent.

POST /token
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=<current refresh token>

The response holds access_token, token_type: "Bearer", expires_in, scope, id_token and the new refresh_token. Store the new refresh token — replacing the old one atomically — before you use the new access token.

Reuse detection

Danger

Sending a refresh token that was already used revokes the whole grant: every access token and refresh token of that sign-in stops working, and the response is invalid_grant. Two concurrent refreshes with the same token have the same effect.

• Serialise refreshes per member: a lock, or a single in-flight refresh promise shared by every caller.
• Never retry a refresh with the old token after a timeout: the first attempt may have succeeded.
• After invalid_grant, send the member through the sign-in again.

When tokens stop working

Besides expiry, a sign-in is revoked when:

• the member changes or resets their password, or changes their username;
• the member’s account is deactivated;
• the office disconnects your application from Settings › Connectors;
• Ubikap disables your client;
• the member leaves their office: /me answers 401 invalid_token and a refresh answers 400 invalid_scope for the office scope.

In every case, start a new sign-in.

Revoking and introspecting

Both endpoints authenticate with your client credentials, and only accept tokens issued to your own client.

• POST /token/revocation with token (and optionally token_type_hint=refresh_token): revoke a token, e.g. when the member signs out of your application.
• POST /token/introspection with token: returns active and, for an active token, its scope, client_id, sub and exp.

See OIDC provider for endpoints and scopes.