For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Help CenterOpenAPI SpecStatus
OverviewInquiriesTransactionsRelaysAPI ReferenceChangelog
OverviewInquiriesTransactionsRelaysAPI ReferenceChangelog
  • Overview
    • Relay Overview
    • Getting Started
  • Widget
    • Usage
  • Integration Methods
    • Server SDK
  • References
    • Relay Widget SDK
    • Server SDK
    • Gateway Service
    • API
    • Schemas
LogoLogo
Help CenterOpenAPI SpecStatus
On this page
  • Endpoints
  • POST /relays
  • POST /relays/privacy-passes
  • POST /relays/:relay-token/redeem
References

Gateway Service Reference

Was this page helpful?
Previous

API Reference

Next
Built with

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

HeaderRequiredDescription
Content-Typetrueapplication/json

Request body

FieldTypeRequiredDescription
claim-typestringtrueThe claim type to evaluate. See Claim types
encryption-key-pemstring | nulltruePEM-encoded RSA public key. If provided, Persona encrypts the claim payload on redemption. Pass null to receive plaintext JSON

Response

FieldTypeDescription
relay-tokenstringIdentifies the relay session. Pass to subsequent privacy pass and redeem calls — store securely on your server
relay-secretstringAuthenticates your server’s calls on this session. Keep server-side — never expose to the client
relay-session-access-tokenstringShort-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.

Request headers

HeaderRequiredDescription
Content-Typetrueapplication/json
AuthorizationtrueBearer <your_api_key>
Persona-Relay-SecrettrueThe relay-secret returned from POST /relays

Request body

FieldTypeRequiredDescription
relay-tokenstringtrueThe relay token returned from POST /relays

Response

FieldTypeDescription
privacy-pass-tokenstringThe 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

ParameterTypeRequiredDescription
relay-tokenstringtrueThe relay token returned from POST /relays

Request headers

HeaderRequiredDescription
Content-Typetrueapplication/json
Persona-Relay-SecrettrueThe relay-secret returned from POST /relays

Request body

FieldTypeRequiredDescription
privacy-pass-tokenstringtrueThe token returned from POST /relays/privacy-passes

Response

FieldTypeDescription
claim-payloadstringPlaintext JSON claim result, or base64-encoded RSA-OAEP ciphertext if encryption-key-pem was set on session creation. See Claim payload schema
token-consumedbooleanWhether the Privacy Pass token was consumed by this redemption. A consumed token cannot be redeemed again