Entitlements

Entitlements are a way to provision an account in your application with specific features or functionality based on the subscription plan a user is on. For example, you might have an “Enterprise” plan that allows users to access certain features like Audit Logs, and a “Basic” plan that does not.

The WorkOS Entitlements integration makes it easy to get Stripe’s entitlement information into your application without needing to listen to Stripe webhooks or explicitly track them in your application.

WorkOS uses Stripe Connect to connect your WorkOS account to your Stripe account. This allows WorkOS to listen to Stripe webhooks on your behalf and keep your users’ entitlements up-to-date.

Entitlements can be enabled in the Authentication section of the WorkOS Dashboard. Clicking Connect will open a new tab on Stripe where you can approve the connection. Once that’s complete, close the tab.

If you decide to disconnect your Stripe account later, you can do so from the same section. Clicking the Manage button will clear out any entitlement data stored in WorkOS and the entitlements claim will no longer be included in access tokens.

WorkOS needs one more piece of information to include entitlements in the access token: the Stripe customer ID for each organization.

Once you have a WorkOS organization ID and a Stripe customer ID, you can set the Stripe customer ID for the organization. One way to handle this is to create a Stripe customer and then set the created Stripe customer ID on the WorkOS organization before redirecting the user to a Stripe checkout page or billing portal. This can be done via the WorkOS API or SDK. Here’s an example using the SDK:

// Create the Stripe customer (using the Stripe SDK)
const customer = await stripe.customers.create({
  email: user.email,
  name: organization.name,
  metadata: {
    organizationId: organization.id,
  },
});

// Tell WorkOS which Stripe customer ID to use for the organization
await workos.organizations.updateOrganization({
  organization: organization.id,
  stripeCustomerId: customer.id,
});

The access token will now include the entitlements claim, containing the user’s entitlements. You can use this information to gate access to features in your application.

Entitlements will show up in the access token the next time the user logs in or the session is refreshed. You can manually refresh the session after the user has completed their subscription purchase. Here’s an example in Express:

app.get('/api/entitlements', async (req, res) => {
  // load the original session
  const session = workos.userManagement.loadSealedSession({
    cookiePassword: process.env.WORKOS_COOKIE_PASSWORD,
    sessionData: req.cookies['wos-session'],
  });

  const { sealedSession, session: newSession } = await session.refresh();
  const { entitlements } = newSession;

  // set the updated refresh session data in a cookie
  res.cookie('wos-session', sealedSession, {
    httpOnly: true,
    sameSite: 'lax',
    secure: true,
  });

  // return the entitlements to the client
  res.json({
    entitlements,
  });
});