API Usage

The API integration gives you full control over the Relay flow. Unlike the Server SDK and Gateway Service, you are responsible for implementing the Privacy Pass protocol yourself.

Creating a Relay session

Create the Relay session before starting your selected client-side integration. Store the 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 https://api.withpersona.com/api/privacy/v1/relays
$
Content-Type: application/json

1
{
2
  "claimType": "age_over18_united_kingdom",
3
  "encryptionKeyPem": "<your_public_key_pem>"
4
}

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

Issuing a Privacy Pass

A Privacy Pass is the billing unit for Relay. It is billed on creation and redeemed to fetch the claim result. The issuance request uses your API key and identifies your platform to Persona for billing. Redemption uses the Privacy Pass token instead of your API key.

Issuance depends only on the claim-type — it is not tied to a specific relay, so you can request a challenge and issue a pass at any time, even before the relay is created.

Get the challenge

Request a challenge for the claim type you want to verify. This call is unauthenticated and returns the values (challenge, token-key, token-key-id) needed to construct a blinded Privacy Pass token.

$
POST https://api.withpersona.com/api/privacy/v1/relays/challenge
$
Content-Type: application/json

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

1
// Response
2
{
3
  "challenge": "<base64url>",
4
  "token-key": "<base64url>",
5
  "token-key-id": "<base64url>"
6
}

Blind, sign, and unblind

Construct your privacy-pass-token using the parsed challenge values. See Challenge Mechanism for the full protocol — including how to parse the challenge, construct the token input, blind the message, and assemble the final token.

Submit the blinded token for signing. This step requires your Persona API key — you can find it in the Persona Dashboard under API Keys.

$
POST https://api.withpersona.com/api/v1/privacy-passes
$
Authorization: Bearer <your_api_key>
$
Content-Type: application/json

1
{
2
  "blindedToken": "<base64url_blindedMsg>",
3
  "keyId": "<token-key-id>"
4
}

1
// Response
2
{
3
  "blind-sig": "<base64url_blind_signature>"
4
}

Unblind blind-sig using your blinding inverse inv and assemble the final privacy-pass-token. See Challenge Mechanism → Step 4.

Redeeming 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.

Redeem the claim from your server using the stored Relay token, Relay secret, and Privacy Pass token. Never expose the Relay secret or Privacy Pass token to the client.

The Privacy Pass token is consumed atomically on a successful claim — once redeemed, it cannot be used again. This creates a risk: if a successful redemption request drops mid-flight and your server never receives the response, retrying with the same token would normally result in a double-spend error.

Using idempotency keys

Pass an Idempotency-Key header on every redemption request. Persona caches the result of the first successful request against that key — if you retry with the same key, the original response is returned without attempting to re-redeem the token.

$
POST https://api.withpersona.com/api/privacy/v1/relays/:relayToken/generate-claim
$
Authorization: PrivateToken token=<privacy-pass-token>
$
Persona-Relay-Secret: <relay-secret>
$
Idempotency-Key: <your_idempotency_key>
$
Content-Type: application/json

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

Recommendations:

• Generate the idempotency key once before the first attempt and reuse it on every retry for the same redemption request
• Use a UUID or other cryptographically random string — do not reuse keys across different relay redemptions
• Keys are pruned after 24 hours — if you retry after that window, a new request is generated

Parsing the claim payload

If you opted out of encryption, parse claim-payload directly:

1
const claim = JSON.parse(claimPayload);
2
console.log(claim.claim_type);   // e.g. 'age_over18_united_kingdom'
3
console.log(claim.claim_result); // 'passed' or 'failed'
4
console.log(claim.methodology);  // array of MethodologyCalculation, if not hidden

If you provided an encryptionKeyPem, decrypt the payload with your private key first:

1
import crypto from 'crypto';
2
3
const decrypted = crypto.privateDecrypt(
4
  { key: '<your_private_key_pem>', padding: crypto.constants.RSA_PKCS1_OAEP_PADDING },
5
  Buffer.from(claimPayload, 'base64')
6
);
7
const claim = JSON.parse(decrypted.toString('utf8'));

See the claim payload schema for the full type definition.