Skip to content

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.

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)
}

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())

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.

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 public https address.
  • Audience (aud): required. Tokens must be issued for this audience, and must have exp.
  • 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 (sub by default), organization (org) and email address (email, the standard OIDC claim).

When a JWKS URL is set, signing secrets are not used.

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_123 has its own read state, apart from a verified user_123 (signed token or the server API). Claiming an id can’t touch a real user’s read state.
  • Its org and createdAt aren’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.

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.