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

Call this before rendering the widget. Store relay-token and relay-secret securely on your server — never expose these to the client. Return relay-session-access-token to your frontend to initialize the widget.

$
POST /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
}

Once your frontend has the access token, initialize the widget and wait for onComplete before proceeding. See Widget usage.

Issuing a Privacy Pass

A Privacy Pass is the billing unit for Relay — billed on creation and 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.

A relay must exist before a Privacy Pass can be issued — the challenge is obtained through the relay’s endpoint. 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.

Get the challenge

Call generate-claim without a PrivateToken header. Persona responds with a 401 containing a WWW-Authenticate header — this is expected, not an error. The values in this header (challenge, token-key, token-key-id) are needed to construct a blinded Privacy Pass token.

$
POST /api/privacy/v1/relays/:relayToken/generate-claim
$
Persona-Relay-Secret: <relay-secret>

$
# Response: 401 Unauthorized
$
WWW-Authenticate: PrivateToken challenge="<base64url>", token-key="<base64url>", token-key-id="<base64url>"

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 /api/v1/privacy-passes
$
Authorization: Bearer <your_api_key>
$
Content-Type: application/json

1
{
2
  "blindedToken": "<base64url_blindedMsg>",
3
  "challengeDigest": "<mac from decoded challenge>",
4
  "keyId": "<token-key-id>"
5
}

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

onComplete should trigger a call to your server to redeem the Privacy Pass.

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