---
url: https://docs.ridgedata.ai/guide/iframe-authentication.md
---
# Iframe authentication

An iframe embed authenticates with a signed URL. You can generate it in Ridge without an API
key or a server endpoint.

## Generate a signed URL

Open the dashboard's **Embed** dialog in Ridge, choose **Iframe Embed**, and generate a URL.
The `token` parameter is an embed-token id, not a JWT. The `sig` parameter is an HMAC
signature tied to the token, dashboard, and any partition restrictions. Copy the complete
URL from Ridge; do not construct or modify its signed parameters.

A missing `token` or `sig` returns `400`. An invalid signature, changed signed parameters,
or revoked token returns `403`.

```html
<iframe src="SIGNED_RIDGE_EMBED_URL" title="Sales dashboard"></iframe>
```

Treat the complete URL as a bearer credential: anyone who has it can view the dashboard
and data that the URL allows.

## Lifecycle and revocation

The URL remains valid until you revoke it from the dashboard's **Embed** dialog. Revoking a URL
leaves the dashboard and other generated URLs unchanged.

The iframe loads data with a 24-hour access token. It renews the token at about 80% of its
lifetime, and Ridge checks the URL again at each renewal.

Revoking the URL stops new page loads at once. An open iframe keeps working until its next
renewal, up to about 19 hours later. Then it asks the viewer to reload. Unpublishing the
dashboard or losing the embedding plan stops an open iframe the same way.

Use a separate URL when viewers need independently revocable access. Generate separate URLs
for customers who need separate access.

## Row-level access

Choose the viewer's partition when generating the URL. The partition parameters are covered
by the signature, so editing or removing them invalidates the credential.

See [Partitioning](./partitioning) for details on row-level access and how partitions differ from
interactive filters.

## Host origin

Any page that holds a signed URL can frame the dashboard and drive it over `postMessage`.
There is no origin allowlist and nothing to configure with Ridge.

The iframe addresses its messages rather than broadcasting them. `ridge:ready` is sent to
whichever page framed the dashboard and carries only the state schema. Every other message,
including `ridge:stateChange` and `ridge:error`, is addressed to the origin of the first
message your app sends to the frame. A host that only listens still needs to send one command
after `ridge:ready`; `ridge:getState` is the natural choice, and its reply carries the current
state.

Because the signed URL is the only credential, a leaked URL lets another site display the
dashboard and read its filter state. Revoke the URL in Ridge if that happens. Open pages stop
at their next token renewal. A token already issued stays valid until it expires, even outside
the page. See [Lifecycle and revocation](#lifecycle-and-revocation).