SDK Integration
Choose between the feature_flags access token claim and the Node runtime client.
There are two ways to read feature flags in your application. Which ones are available to you depends on the platform. The runtime client ships in the Node SDK only. If your backend runs on Node, use the runtime client.
| Platform | Approach | Flag changes take effect |
|---|---|---|
| Node | Node runtime client | Within the polling interval |
| Any other platform | feature_flags access token claim |
Next time the session refreshes |
Why the runtime client is the better default on Node.
- Every flag in the
feature_flagsclaim takes up space in the access token, which is stored in the AuthKit session cookie. - Browsers cap how large a cookie can be and JWT templates must render to 3072 bytes or smaller. A growing flag set eats into that budget, and so do role and permission claims.
- The runtime client evaluates flags server-side without putting them in the token, so the number of flags stops being a constraint.
Use the runtime client for server-side evaluation that stays in sync independently of user authentication, such as in backend services, jobs, webhooks, or other long-lived server processes. It keeps every active flag out of the user’s access token and session cookie, which makes it the right default for an application whose flag set grows over time.
See the Node runtime client guide for setup, evaluation, and shutdown. It applies to Node only.
Read the claim to gate authenticated application behavior from the user’s session, when flag updates can wait until the session refreshes. On platforms without a runtime client this is how you use feature flags. On Node it still works well for a small, stable set of flags.
The claim travels inside the access token, so this approach works on any platform whose AuthKit SDK gives you an authenticated session.
See the access token claim guide for reading it from a session, and for reading it straight from the token where an SDK does not surface it.
