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 either be stored in a secure cookie or 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 or Remix 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:

Refresh 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.

Refresh tokens can be used to obtain a new access token for a different organization by passing the organization_id parameter to the authenticate with refresh token endpoint. If the session for the refresh token is authorized to access the organization, then the org_id will be set to the given organization, along with the role and permissions claims matching the user’s membership in that organization.

If the user is not authorized for the organization, then an appropriate authentication error will be returned and the user will need to authenticate. Applications using AuthKit can use the Get Authorization URL and the organization_id parameter to initiate the authentication flow specifically for the organization.

When a user signs out of your app, the following steps should occur:

Example

// 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: