> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.withpersona.com/2020-05-18/relay-hosted-flow/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.withpersona.com/_mcp/server.

# Hosted Flow

> Open Relay on a Persona-hosted page instead of embedding the Widget.

Hosted Flow runs the user-facing Relay verification on a Persona-hosted page. Use it when you want to keep verification separate from your website instead of embedding the Relay Widget. For some organizations, that distinct experience helps reinforce Relay's privacy-preserving design for users.

![Hosted Flow uses the Relay session access token to run the user-facing verification.](https://assets.withpersona.com/f_auto,q_auto/developer-docs/images/relay-integration-overview-phase2.png)

## Prerequisites

Your server must first create a Relay session using a [server-side integration method](/relay-getting-started#server-side-integration-methods).

## Construct the Hosted Flow URL

Pass the Relay session access token to the production Hosted Flow URL. You can also set the optional `theme` query param to `light`, `dark`, or `auto` (default `auto`):

```text
https://relay.withpersona.com/relay?relay-session-access-token=<URL_ENCODED_TOKEN>&theme=<THEME>
```

Use `URL` and `URLSearchParams` to encode the token correctly:

```javascript
const url = new URL("https://relay.withpersona.com/relay");
url.searchParams.set(
  "relay-session-access-token",
  relaySessionAccessToken,
);
url.searchParams.set("theme", "auto");
const hostedFlowUrl = url.toString();
```

## Open Hosted Flow

Open the URL in a new tab without a referrer:

```html
<a
  href="<HOSTED_FLOW_URL>"
  target="_blank"
  rel="noopener noreferrer"
>
  Verify with Persona
</a>
```

Hosted Flow requires that the request arrive without a `Referer` header. Persona rejects Hosted Flow requests that include one — this is enforced, not just recommended. A user can verify that themselves by opening Hosted Flow from a page that sends a referrer and confirming the request is rejected.

A referrer would disclose your site's domain to Persona and create a signal that could associate the verification with your platform. Preventing that disclosure is part of Relay's design.

Hosted Flow intentionally does not redirect the user back to your site. A redirect destination would reveal your domain to Persona and create another signal that could associate the verification with the requesting platform.

When verification finishes, Hosted Flow tells the user that they can close the page.

## Retrieve the claim result

Hosted Flow does not invoke an `onComplete` callback, redirect to your site, or send a completion `postMessage` to the original page.

Your backend should retrieve the claim using your selected [server-side integration method](/relay-getting-started#server-side-integration-methods).

Stop polling when the claim becomes available or according to your application's timeout and error-handling policy.

## Security

> **Warning**
>
> Store the Relay secret securely on your server. Never expose it to the client.

## Try Hosted Flow

> Open Relay on a Persona-hosted page instead of embedding the Widget.