Gateway Service Reference

This page documents the full HTTP API for the Persona Relay Gateway Service.

Endpoints

`POST /relays`

Creates a Relay session. No authentication required.

Request headers

Header	Required	Description
`Content-Type`	true	`application/json`

Request body

Field	Type	Required	Description
`claim-type`	`string`	true	The claim type to evaluate. See Claim types
`encryption-key-pem`	`string \| null`	true	PEM-encoded RSA public key. If provided, Persona encrypts the claim payload on redemption. Pass `null` to receive plaintext JSON

Response

Field	Type	Description
`relay-token`	`string`	Identifies the relay session. Pass to subsequent privacy pass and redeem calls — store securely on your server
`relay-secret`	`string`	Authenticates your server’s calls on this session. Keep server-side — never expose to the client
`relay-session-access-token`	`string`	Short-lived token passed to the client-side widget via your server

`POST /relays/privacy-passes`

Issues a Privacy Pass token. Handles the full blind RSA protocol internally. Requires your API key — this is the billing point for Relay.

How does this work?

Curious how the Privacy Pass protocol works under the hood? See Privacy Pass Protocol for a full walkthrough — relevant if you’re implementing this yourself without the gateway.

Issue against the same claim type as your relay

The signing key you receive is determined by the claim-type you issue against, so each Privacy Pass is bound to that claim type. A pass can only redeem a relay created with the same claim type — if they don’t match, the pass won’t be able to redeem the claim.

Request headers

Header	Required	Description
`Content-Type`	true	`application/json`
`Authorization`	true	`Bearer <your_api_key>`

Request body

Field	Type	Required	Description
`claim-type`	`string`	true	The claim type to issue a Privacy Pass for. Must match the claim type of the relay you’ll redeem against. See Claim types

Response

Field	Type	Description
`privacy-pass-token`	`string`	The issued Privacy Pass token. Hold this server-side until the user completes verification, then pass to the redeem endpoint

`POST /relays/:relay-token/redeem`

Redeems a Privacy Pass token and returns the claim result.

Path parameters

Parameter	Type	Required	Description
`relay-token`	`string`	true	The relay token returned from `POST /relays`

Request headers

Header	Required	Description
`Content-Type`	true	`application/json`
`Persona-Relay-Secret`	true	The `relay-secret` returned from `POST /relays`

Request body

Field	Type	Required	Description
`privacy-pass-token`	`string`	true	The token returned from `POST /relays/privacy-passes`

Response

Field	Type	Description
`claim-payload`	`string`	Plaintext JSON claim result, or base64-encoded RSA-OAEP ciphertext if `encryption-key-pem` was set on session creation. See Claim payload schema
`token-consumed`	`boolean`	Whether the Privacy Pass token was consumed by this redemption. A consumed token cannot be redeemed again