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 rendering the widget. The response includes a session access token to pass to your frontend, along with a relay-token and relay-secret that you must store securely on your server — never expose these to the 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
}

Store relay-token and relay-secret securely on your server. Return relay-session-access-token to your frontend to initialize the widget. See Widget usage.

Step 2 — Issue a Privacy Pass

A Privacy Pass is the billing unit for Relay — it is billed on creation and is what gets redeemed to fetch the claim result. Since issuance uses your API key, Persona knows your platform identity at this point for billing purposes. Redemption remains fully anonymous — Persona does not know who redeems the claim. Each Privacy Pass can only be redeemed once, so we recommend storing privacy-pass-token on your end and mapping it to the corresponding relay.

This endpoint requires a relay to exist — the challenge is obtained through the relay’s endpoint — but can be called at any point after relay creation and before redemption. Issuing immediately after creating the relay, before the widget completes, is recommended: it makes it harder for Persona to correlate your platform identity to a relay via timing. 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>
$
Persona-Relay-Secret: <relay-secret>

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

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

Step 3 — Redeem and retrieve the claim

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>" }'
$
$
# ---- Widget handles user verification on the frontend ----
$
$
# 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>" \
>
  -H "Persona-Relay-Secret: <relay-secret>" \
>
  -d '{ "relay-token": "<relay-token>" }'
$
$
# 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>" }'