Usage

The gateway exposes three endpoints that map directly to the Relay Server SDK methods. You can use any HTTP client in any language.

Step 1 — Create a Relay session

Call this endpoint before starting your selected client-side integration. Store the returned Relay token and Relay secret on your server — never expose the Relay secret to the client. Return the Relay session access token to your client.

$
POST /relays

1
// Request
2
{
3
  "claim-type": "age_over18_united_kingdom",
4
  "encryption-key-pem": "<your_public_key_pem>" // pass null to opt out of encryption
5
}

1
// Response
2
{
3
  "relay-token": "<relay-token>",
4
  "relay-secret": "<relay-secret>",
5
  "relay-session-access-token": "<relay-session-access-token>"
6
}

Pass the Relay session access token to the Embedded Widget, Hosted Flow, iOS SDK, or Android SDK.

Step 2 — Issue a Privacy Pass

A Privacy Pass is the billing unit for Relay. It is billed on creation and redeemed to fetch the claim result. Issuance uses your API key and identifies your platform to Persona for billing. Redemption uses the Privacy Pass token instead of your API key. Each Privacy Pass can only be redeemed once. Store privacy-pass-token on your server and map it to the corresponding Relay session.

This endpoint depends only on the claim type — it is not tied to a specific relay, so it can be called at any time, even before the relay is created. One Privacy Pass must exist before you can redeem any relay.

This step requires your Persona API key — you can find it in the Persona Dashboard under API Keys.

$
POST /relays/privacy-passes
$
Authorization: Bearer <your_api_key>

1
// Request
2
{
3
  "claim-type": "age_over18_united_kingdom"
4
}

1
// Response
2
{
3
  "privacy-pass-token": "<privacy-pass-token>"
4
}

Step 3 — Redeem and retrieve the claim

Begin claim retrieval when your client-side integration indicates that the user-facing flow is complete:

• Embedded Widget: Call your server from onComplete.
• Hosted Flow: Begin polling your backend when the user launches Hosted Flow.
• iOS SDK and Android SDK: Call your server after the platform’s normal Inquiry completion mechanism reports that the user-facing experience ended.

The Privacy Pass is redeemed only on a successful claim. Since each pass can only be redeemed once, retrying a successful request with the same already-spent token — for example, after a network drop — would normally result in a double-spend error. Idempotency is handled automatically by the gateway.

claim-payload is passed through as-is from Persona. If you provided an encryption-key-pem in Step 1, decrypt it with your private key before parsing. Otherwise it is a plaintext JSON string — see Parsing the claim payload.

$
POST /relays/:relay-token/redeem
$
Persona-Relay-Secret: <relay-secret>

1
// Request
2
{
3
  "privacy-pass-token": "<privacy-pass-token>"
4
}

1
// Response
2
{
3
  "claim-payload": "<encrypted_or_plaintext_claim>",
4
  "token-consumed": true
5
}

Full example

$
# Step 1 — Create a Relay session
$
curl -X POST https://<your-gateway>/relays \
>
  -H "Content-Type: application/json" \
>
  -d '{ "claim-type": "age_over18_united_kingdom", "encryption-key-pem": "<your_public_key_pem>" }'
$
$
# Step 2 — Issue a Privacy Pass
$
curl -X POST https://<your-gateway>/relays/privacy-passes \
>
  -H "Content-Type: application/json" \
>
  -H "Authorization: Bearer <your_api_key>" \
>
  -d '{ "claim-type": "age_over18_united_kingdom" }'
$
$
# Step 3 — Redeem and retrieve the claim
$
curl -X POST https://<your-gateway>/relays/<relay-token>/redeem \
>
  -H "Content-Type: application/json" \
>
  -H "Persona-Relay-Secret: <relay-secret>" \
>
  -d '{ "privacy-pass-token": "<privacy-pass-token>" }'