Anyone can put a
context in your URL. Trust nothing in it until your server
has checked it:
- Signature. Compute HMAC-SHA256 of the
contextparameter with your client secret, and compare it tosignaturein constant time. - Decode. Decode
contextfrom base64url, and parse the JSON. - Expiry. Refuse it once
x.exp, in seconds since the epoch, has passed. Contexts are good for five minutes. - Replay. Refuse an
x.jtiyou’ve already accepted, so a copied URL can’t be opened again. Remember each one until itsx.exp.
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:- Start the rotation, and deploy a check that accepts a signature from either the old secret or the new one.
- Complete the rotation. New contexts are signed with the new secret.
- 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.previewistrue.- The agent, contact and org are made up:
user.idis alwaysrollout-preview-user,crm.personIdisrollout-preview-person, andcrm.accountIdandorg.idarerollout-preview-account. - There is no
account. x.marketplaceId,x.platformandx.appIdare real. When you’re not listed in any marketplace yet, a sample names a placeholder,mkt_sampleon platformsample.
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.