> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omni.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrating to the v1 embed standard SSO signing format

> Learn what changed in the v1 embed standard SSO signing format and how to update your code from v0.

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.

<Note>
  See the [v1 standard SSO guide](/embed/setup/standard-sso/latest) for step-by-step instructions on setting up standard SSO with the v1 format.
</Note>

<h2 id="sdk-functions">
  SDK functions
</h2>

In [`@omni-co/embed`](https://www.npmjs.com/package/@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:

| v1 function                | v0 equivalent                        | Generates a URL for      |
| -------------------------- | ------------------------------------ | ------------------------ |
| `embedSsoDashboard`        | `deprecatedEmbedSsoDashboard`        | A dashboard              |
| `embedSsoWorkbook`         | `deprecatedEmbedSsoWorkbook`         | A workbook               |
| `embedSsoApp`              | `deprecatedEmbedSsoApp`              | An app                   |
| `embedSsoContentDiscovery` | `deprecatedEmbedSsoContentDiscovery` | A content discovery page |

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](#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](#url-expiry) for more information.

<Warning>
  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.
</Warning>

<h2 id="parameters">
  JSON-valued parameters
</h2>

The [v1 SDK functions](#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:

```json wrap v0 parameter example theme={null}
userAttributes=%7B%22country%22%3A%22Townsville%22%7D
```

In v1, you instead pass the JSON as-is:

```json wrap v1 parameter example theme={null}
userAttributes={"country":"Townsville"}
```

## New parameters

<h3 id="url-expiry">
  exp (URL expiry)
</h3>

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.

<Note>
  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.
</Note>

## Removed parameters

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

## Next steps

* [Set up embed standard SSO with the v1 signed payload format](/embed/setup/standard-sso/latest)