Identity
Read state and targeting depend on knowing who the user is. The browser can’t be trusted to say that itself, so rollout accepts three kinds of identity. You choose under Settings → User identity.
| Mode | How | Targeting |
|---|---|---|
| Signed token | Your server signs an HS256 JWT with the project’s signing secret. | Yes |
| Your auth provider | Your provider (Clerk, Auth0, …) signs the JWT; rollout checks it via JWKS. | Yes |
| Unverified (opt-in) | The SDK sends a plain user id. | No |
The SDK sends tokens as Authorization: Bearer <token> along with the publishable key in
X-Rollout-Key.
Signed tokens (HS256)
Section titled “Signed tokens (HS256)”Generate a signing secret under Settings → User identity (it starts with rollout_sig_). On your
server, sign a short-lived HS256 JWT for the signed-in user.
| Claim | Required | Description |
|---|---|---|
sub |
Yes | Your user id, any string up to 256 characters. |
exp |
Yes | Expiry. Keep it short, e.g. one hour; the SDK fetches a new token after a 401. |
org |
No | The organization or account the user belongs to. |
created_at |
No | When the user signed up, as Unix seconds or an ISO date. Older announcements start out read. |
attrs |
No | An object of custom attributes for targeting, e.g. { "plan": "pro" }. |
email |
No | Where announcement emails go. Ignored if the token has email_verified: false. |
rollout stores attrs and email on the user, so the dashboard and the server API
see them too. A token without them keeps the stored values. Consent to emails is never read from
tokens: set it through the server API.
import { SignJWT } from 'jose'
const secret = new TextEncoder().encode(process.env.ROLLOUT_SIGNING_SECRET)
export function rolloutToken(user) { return new SignJWT({ org: user.orgId, created_at: Math.floor(user.createdAt.getTime() / 1000), attrs: { plan: user.plan, role: user.role }, }) .setProtectedHeader({ alg: 'HS256' }) .setSubject(user.id) .setExpirationTime('1h') .sign(secret)}import jwt from 'jsonwebtoken'
export function rolloutToken(user) { return jwt.sign( { sub: user.id, org: user.orgId, created_at: Math.floor(user.createdAt.getTime() / 1000), attrs: { plan: user.plan }, }, process.env.ROLLOUT_SIGNING_SECRET, { algorithm: 'HS256', expiresIn: '1h' }, )}Serve it from an endpoint your frontend can call, and pass a function to the SDK so it can fetch fresh tokens:
feed.token = () => fetch('/api/rollout-token').then((r) => r.text())Rotating the secret
Section titled “Rotating the secret”A project can have several active secrets; rollout accepts a token signed with any of them. Generate a new secret, deploy it to your servers, then retire the old one under Settings → User identity. Tokens signed with a retired secret are rejected.
Your auth provider (JWKS)
Section titled “Your auth provider (JWKS)”If your users already have a JWT from an auth provider, rollout can verify it against the provider’s public keys instead. You don’t sign anything or manage a secret: the provider signs the token with its own private key, and rollout checks it with the public keys at the JWKS URL. Under Settings → User identity, set:
- JWKS URL: the provider’s key set, e.g.
https://your-app.clerk.accounts.dev/.well-known/jwks.json. It must be a publichttpsaddress. - Audience (
aud): required. Tokens must be issued for this audience, and must haveexp. - Issuer (
iss): optional. If set, tokens must come from this issuer. Recommended when your provider signs tokens for other apps with the same keys. - Claim mapping: which claims hold the user id (
subby default), organization (org) and email address (email, the standard OIDC claim).
When a JWKS URL is set, signing secrets are not used.
Unverified users
Section titled “Unverified users”If you allow it under Settings → User identity (“Also allow unverified users”), the SDK can pass a plain identity instead of a token:
feed.user = { id: 'user_123', org: 'org_42', createdAt: '2025-01-10T00:00:00Z' }The SDK sends it base64url-encoded in the X-Rollout-User header. Anyone can claim any id this
way, so rollout treats unverified users as separate users:
- An unverified
user_123has its own read state, apart from a verifieduser_123(signed token or the server API). Claiming an id can’t touch a real user’s read state. - Its
organdcreatedAtaren’t stored, and targeted announcements are never shown to it. - In the dashboard it’s marked Unverified.
Use it for prototypes or public, logged-out pages only.
Errors
Section titled “Errors”| Code | Meaning |
|---|---|
identity_required |
No token and no unverified user was sent. |
invalid_token |
Bad signature, wrong audience or issuer, missing exp, expired, or an HS256 token with JWKS. |
invalid_identity |
No usable user id (sub), an id or org over 256 characters, or a malformed X-Rollout-User. |
invalid_key |
The publishable key is unknown or revoked. |
too_many_new_users |
429: over 1000 new unverified users in this project in the last hour. |
verified_identity_required |
An unverified user was sent, but the project requires tokens. |
origin_not_allowed |
The page’s origin isn’t in Settings → Keys & origins → Allowed origins. |