Skip to main content
The v1 signing format replaces the deprecated v0 format. The v0 format will be unsupported after October 1, 2026, and removed by January 1, 2027. Use this page to learn what changed in v1 and what to update in your code.
See the v1 standard SSO guide for step-by-step instructions on setting up standard SSO with the v1 format.

​
SDK functions

In @omni-co/embed v1.0.0 and later, the original function names now produce v1 URLs. The v0 builders are still exported, renamed with a deprecated prefix: Both formats are temporarily accepted at /embed/login. The v1 functions accept the same parameters, with two differences:
  • JSON-valued parameters are passed as objects and arrays instead of pre-stringified strings. See JSON-valued parameters for more information.
  • expiresIn sets how long the generated URL stays valid. The deprecatedEmbedSso* builders accept and ignore it, because v0 URLs have nowhere to carry an expiry. See URL expiry for more information.
Upgrading to v1.0.0 without changing your code will change the URLs you generate. Existing calls to embedSsoDashboard and its siblings keep working but will produce v1 URLs. Expect the new shape if anything on your side inspects, logs, or reconstructs these URLs.

​
JSON-valued parameters

The v1 SDK functions accept the same parameters they did in v0, but parameters structured as JSON are now passed as objects and arrays instead of pre-stringified strings. In v0, you needed to stringify and then URL encode parameters with JSON values. For example:
v0 parameter example
In v1, you instead pass the JSON as-is:
v1 parameter example

​
New parameters

​
exp (URL expiry)

Every v1 payload carries an exp parameter: the absolute moment the URL stops being valid, in epoch seconds, following the JWT convention.
  • If you use the SDK, the SDK sets exp to 24 hours out by default. Use the expiresIn parameter to change the lifetime.
  • If you generate URLs manually, set exp yourself as part of the payload. Set it no more than seven days out to match the ceiling the SDK enforces.
Because exp is included in the payload, the signature already covers it. There’s no separate query parameter, and a URL’s expiry can’t be changed without re-signing. When defining URL expiry, keep in mind that shorter expiries are better. Until the embed URL is redeemed, it’s a bearer credential - anyone who has it can start the session it describes, and URLs leak through browser history, referer headers, screenshots, and proxy logs. Generate URLs on demand where you can, and only use a longer lifetime when needed, such as a URL that goes out in an email or gets built by a nightly job.
Omni currently requires exp to be present, but doesn’t yet reject URLs whose expiry has passed. By October 2026, Omni will begin enforcing URL expiry and reject payloads that don’t include an exp parameter. Migrate your code before then to avoid disruptions.

​
Removed parameters

The domain parameter was removed in v1.0.0. Use host instead.

​
Next steps