Access token claim

When present, the feature_flags claim in an AuthKit access token holds the slugs of the flags enabled for that user, based on your organization and user targeting rules. Reading it needs no extra request: the flags arrive with the session the user already has.

The trade is freshness. A flag you change in the dashboard reaches the user the next time they sign in or their session refreshes, rather than within a polling interval. You can force it sooner by refreshing the session.

Load the sealed session from your cookie, authenticate it, then read the flags off the result. The claim is part of the access token, so this works on any platform whose AuthKit SDK gives you an authenticated session.

require "workos"

workos = WorkOS::Client.new(
  api_key: ENV["WORKOS_API_KEY"],
  client_id: ENV["WORKOS_CLIENT_ID"]
)

session = workos.session_manager.load(
  seal_data: cookies["wos_session"],
  cookie_password: ENV["WORKOS_COOKIE_PASSWORD"]
)

result = session.authenticate

if result[:authenticated] && result[:feature_flags]&.include?("advanced-analytics")
  # Show the feature
end

In @workos-inc/authkit-nextjs you can skip the manual load and read the claim from withAuth() instead, as the quick start guide shows.

Where an SDK’s session helper does not surface the flags, the claim is still in the token. Verify the access token against your environment’s JWKS endpoint and read feature_flags from the payload. The access token reference documents every claim it carries.

This is also the approach to reach for in a service that receives an access token but has no cookie or session of its own.

Every flag in the claim takes up space in the access token, which is stored in the AuthKit session cookie, and browsers cap how large a cookie can be. That budget is shared with your role, permission, and entitlement claims, and JWT templates must render to 3072 bytes or smaller.