Learn more about integrating sessions.
When a user signs in to your app, a user session is created. Along with the User object, a successful authentication response will include an access token and refresh token. Your application can use these tokens to ensure that the user’s session is still active.
Each user session can be viewed from within the WorkOS dashboard:
Navigate to Users and select a user. Then, switch to Sessions tab and click on a user session to get more information.
Successful authentication responses will include both an access token and a refresh token. The access token should be stored as a secure cookie in the user’s browser and should be validated by the backend on each request. The refresh token should be persisted on your backend. Once the access token has expired, a new one can be obtained using the refresh token.
If you’re using our Next SDK, all the work of validating access tokens and refreshing expired tokens is handled for you (more framework support coming soon). Read on for details about how token handling works.
The access token is a JSON Web Token (JWT), which should be validated on each request using a library like jose. The signing JWKS can be found at http://api.workos.com/sso/jwks/<clientId>
. The JWT includes the following claims:
sub
: the WorkOS user idsid
: the session ID (used for signing out)iss
: https://api.workos.com/
(will be your custom auth domain if configured)org_id
: The organization that was selected at sign-in time (if applicable)exp
: standard expires_at claim (the token should not be trusted after this time)iat
: standard issued_at claimRefresh tokens should be persisted on the backend in, for instance, a database, cache, or secure http-only cookie. A new access token can be obtained by using the authenticate with refresh token endpoint. If the session is still active, a new access token and refresh token will be returned. Refresh tokens are single use, so be sure to replace the old refresh token with the newly generated one.
When a user signs out of your app, the following steps should occur:
sid
claim) out of the access token.
// extract sessionId from access token const sessionId = jose.decodeJwt(session.accessToken).sid; // delete app session cookie cookies().delete('my-app-sesssion'); // redirect to logout endpoint // (the user will be redirected to your app homepage url // after the logout completes) redirect(workos.userManagement.getLogoutUrl({ sessionId }));
Using the WorkOS dashboard you can configure how Sessions work in your integration. You’ll find the settings in the Authentication section.
Additionally, make sure to review your settings in the Redirect section: