Sessions

Learn more about integrating sessions.

Introduction

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.

Integrating Sessions

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.

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

sub: the WorkOS user id

sid: 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)

role: the role of the selected organization membership (only applicable if an organization is selected)

permissions: the permissions assigned to the role (if applicable)

exp: the standard expires_at claim (the token should not be trusted after this time)

iat: the standard issued_at claim

Refresh Token

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.

Switching Organizations

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.

Signing Out

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

Get the session id (sid claim) out of the access token.

Delete the user’s app session.

Redirect the user’s browser to logout endpoint endpoint (this will ensure the user’s session ends at WorkOS).

The user will be redirected back to the URL configured as your App homepage URL

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 }));

Configuring Sessions

Using the WorkOS dashboard you can configure how Sessions work in your integration. You’ll find the settings in the Authentication section.

Maximum session length: The session will expire after this length of time. Once expired the user will need to sign in again.

Access token duration: Your backend can verify the access token on each request (see the Integrating Sessions section above). It’s recommended to keep the access token duration short so that changes in the session are quickly reflected in your app.

Additionally, make sure to review your settings in the Redirect section:

App homepage URL: Specifies where users are redirected after logging out. If not set, the user will be redirected to an error page.

InvitationsEasily add users to your application or as members of an organization

Up next