Refresh & logout flow
🔑 Auth:
client_id+client_secret+refresh_token(backend only) · 🔁 Rotation: every refresh returns a NEW refresh token · 🚪 Logout: RP-initiated viaend_session_endpoint
Access tokens live ~1 hour (expires_in = 3600). The refresh grant renews them from your
backend without bothering the user — for up to 30 days per refresh-token family.
How it works
Steps
POST https://idp.valyd.work/api/auth/oidc/token(form-encoded) withgrant_type=refresh_token,refresh_token=…, and your client credentials (HTTP Basic orclient_id+client_secretin the body — not both). Optionally passscopeto narrow the new access token to a subset of the originally granted scopes; asking for more returnsinvalid_scope.- Read the top-level response: a fresh
access_tokenand a newrefresh_token. Failures are standard OAuth 2.0 errors, e.g.400 { "error": "invalid_grant", "error_description": "…" }— treatinvalid_grantas “the user must sign in again”. - Persist the new refresh token, atomically replacing the old one. With the SDK
(
@valyd/sdk):const next = await valyd.auth.refreshToken(stored)— store bothnext.accessTokenandnext.refreshToken.
Rotation & theft detection
- Rotation is on for every refresh: the token you sent is revoked the moment the new one is issued. A “refresh token” is therefore a chain, not a value — always save the latest link.
- Replaying a rotated-away token is treated as theft and revokes every refresh token for that user and client. That’s a feature: if a token is stolen, either the thief or the real client eventually replays a stale one, and the whole family dies instead of living for 30 days.
- Refresh tokens are client-bound — a token leaked from one app cannot be used by another.
- Practical consequences: don’t refresh the same stored token from two processes concurrently, and if your persist step can fail, treat “refresh succeeded but save failed” as a forced re-login.
Logout & revocation
RP-initiated logout is https://idp.valyd.work/api/auth/oidc/logout (GET or POST), advertised
in discovery as end_session_endpoint:
https://idp.valyd.work/api/auth/oidc/logout?id_token_hint=ID_TOKEN&post_logout_redirect_uri=https://yourapp.com/logged-out&state=RANDOMid_token_hint— theid_tokenfrom login (recommended); an expired one is accepted (its signature still proves the user/client). Without a valid hint the user sees a “Sign out of Valyd?” confirmation page first.client_id— optional; identifies your app when you don’t sendid_token_hint.post_logout_redirect_uri— must be registered for your client. First-party clients use their registered post-logout URIs. Developer-portal apps may, for now, use one of their registered redirect URIs (transitional — sunset 2026-12-01, see Deprecations). An unregistered value shows an error page instead of redirecting.state— optional, appended to the post-logout redirect.
Logout ends the user’s Valyd session in that browser (Valyd cookies cleared, the IdP
session’s refresh token revoked, the Valyd web app’s storage cleared) and revokes the user’s
refresh and access tokens for your client, then redirects. Also clear your own app session —
Valyd can’t do that for you. With the SDK:
valyd.auth.getEndSessionUrl({ idTokenHint, postLogoutRedirectUri, state }).
Build it
- Where the first refresh token comes from: Authorization Code flow
- Token/logout endpoint details: API reference
- Lifetimes and claims: Tokens
- Login session vs verification session: Sessions