<!-- llms.txt: https://workos.com/llms.txt -->

# Access token claim

## Overview

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](https://workos.com/docs/reference/authkit/authentication/refresh-token).

***

## Reading the claim from a 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.

:::code-group

```rb language="ruby" title="Ruby" tab="1"
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`](https://workos.com/docs/sdks/authkit-nextjs) you can skip the manual load and read the claim from `withAuth()` instead, as the [quick start guide](https://workos.com/docs/feature-flags) shows.

***

## Reading the claim from the access token directly

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](https://workos.com/docs/reference/authkit/session-tokens/jwks) and read `feature_flags` from the payload. The [access token reference](https://workos.com/docs/reference/authkit/session-tokens/access-token) 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.

***

## Keeping the token small

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](https://workos.com/docs/authkit/jwt-templates#size-limits).

> **Note:** **On Node, prefer the runtime client for a large flag set.** The [Node runtime client](https://workos.com/docs/feature-flags/node-runtime-client) evaluates flags server-side without putting them in the token, so the number of flags stops competing with your other claims for room. It ships in [`@workos-inc/node`](https://workos.com/docs/sdks/node) only.