Skip to content

Refresh tokens

Access tokens expire after 30 minutes. If your RP needs to read consented data after the user's browser session ends, request the offline_access scope and store the refresh token securely.

Enable refresh

  1. At registration, add the refresh_token grant type.
  2. Include offline_access in the authorization request scope:

text scope=openid%20offline_access

The consent screen discloses ongoing access as its own line. If the user approves, the token response includes a refresh_token.

Exchange the refresh token

curl -sS -X POST "https://id.trustnet.app/oauth2/token" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=refresh_token" \
  --data-urlencode "refresh_token=$REFRESH_TOKEN"

The response has the standard token shape. Use the new access_token; if a new id_token is present, replace the old one. Persist any returned refresh token if your client library rotates them.

Refresh tokens are valid for 30 days and are invalidated immediately when the user revokes your RP's access or their session is torn down.

When refresh fails

Response Meaning Action
400 invalid_grant The refresh token is expired, revoked or otherwise invalid. Do not retry. Send the user through a new authorization request.
401 invalid_client The client credentials are wrong. Check the client secret; reissue it in the portal if necessary.
503 / 5xx Transient upstream failure. Retry with backoff, within your own request budget.

Never treat a revoked refresh token as a reason to retry aggressively: the user has explicitly ended access. Clear your stored token and stop.

Security notes

  • Store refresh tokens encrypted at rest and never in client-side code.
  • Do not log refresh tokens or token responses.
  • Request offline_access only when you actually need ongoing access. The consent screen tells the user that access continues.