Hosted Flow

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.

Prerequisites

Your server must first create a Relay session using a server-side integration method.

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):

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

Use URL and URLSearchParams to encode the token correctly:

1
const url = new URL("https://relay.withpersona.com/relay");
2
url.searchParams.set(
3
  "relay-session-access-token",
4
  relaySessionAccessToken,
5
);
6
url.searchParams.set("theme", "auto");
7
const hostedFlowUrl = url.toString();

Open Hosted Flow

Open the URL in a new tab without a referrer:

1
<a
2
  href="<HOSTED_FLOW_URL>"
3
  target="_blank"
4
  rel="noopener noreferrer"
5
>
6
  Verify with Persona
7
</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.

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

Security