Skip to main content
Every time Rollout loads your app, it adds two query parameters to your app URL:
Anyone can put a context in your URL. Trust nothing in it until your server has checked it:
  1. Signature. Compute HMAC-SHA256 of the context parameter with your client secret, and compare it to signature in constant time.
  2. Decode. Decode context from base64url, and parse the JSON.
  3. Expiry. Refuse it once x.exp, in seconds since the epoch, has passed. Contexts are good for five minutes.
  4. Replay. Refuse an x.jti you’ve already accepted, so a copied URL can’t be opened again. Remember each one until its x.exp.
Do this on your server, never in the browser: the check needs your client secret.
rememberJti is yours to write: a set in Redis with a time to live, or a database table with a unique key, works. It returns false when the id is already stored. In Java and C#, it’s a static method on the same class.
The signature and the encoding are the same as Follow Up Boss’s embedded apps. A check written for FUB works once it uses your Rollout secret. The expiry and replay checks are new, and recommended.

Rotating your client secret

Contexts are signed only with your Current secret. When you rotate it from the dashboard’s API page, the new secret signs nothing until the rotation completes: when you choose Complete rotation, or when the old secret is retired. To rotate without failing any launch:
  1. Start the rotation, and deploy a check that accepts a signature from either the old secret or the new one.
  2. Complete the rotation. New contexts are signed with the new secret.
  3. Wait five minutes, for the last contexts signed with the old secret to expire, then remove the old secret from your check.

Previews

When a CRM reviews your listing, it sees your app in a preview. The signed sample in your dashboard is a preview too. A preview is signed exactly like a real launch, with your secret, so your check accepts it. But:
  • x.preview is true.
  • The agent, contact and org are made up: user.id is always rollout-preview-user, crm.personId is rollout-preview-person, and crm.accountId and org.id are rollout-preview-account.
  • There is no account.
  • x.marketplaceId, x.platform and x.appId are real. When you’re not listed in any marketplace yet, a sample names a placeholder, mkt_sample on platform sample.
When x.preview is true, show your app as a signed-in agent would see it, with sample data, so the reviewer can judge it. Don’t link the preview’s user.id to any of your users, and don’t write anything to a CRM.