Server SDK Reference

This page documents the full server-side API for the Persona Relay SDK.

Installation

Node.js

Go

Available on npm as @persona/sdk-node.

$ npm install @persona/sdk-node

Constructor

Node.js

Go

1 import Persona from '@persona/sdk-node';
2 
3 const persona = new Persona({ apiKey: '<your_api_key>' });

Arguments — PersonaOptions

Option	Type	Required	Description
`apiKey`	`string`	false	Your Persona API key. Not required for relay session creation (`persona.relays.create`), but may be required for other Persona API calls

Methods

Node.js

Go

Relay methods are available on the persona.relays namespace.

`create`

Creates a Persona relay session. No API key required.

Node.js

Go

1 const session = await persona.relays.create({
2   claimType: "age_18_plus_verified",
3   encryptionKeyPem: "<your_public_key_pem>",
4 });

Arguments — CreateRelayParams

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

Returns — CreateRelayResponse

Field	Type	Description
`relayToken`	`string`	Identifies the relay session. Pass to the subsequent `generateClaim` call
`relaySecret`	`string`	Authenticates your server’s calls on this session. Keep server-side — never expose to the client
`relaySessionAccessToken`	`string`	Short-lived token passed to the client-side widget via your server

`issuePrivacyPass`

Runs the full blind RSA issuance flow and returns a Privacy Pass token. The SDK handles all cryptography internally.

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

Issuance depends only on the claim type — it is not tied to a relay, so it can run at any time, including before the relay is created.

Issue against the same claim type as your relay

The signing key the SDK fetches is determined by the claim type you pass, 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.

Node.js

Go

1 const { privacyPassToken } = await persona.relays.issuePrivacyPass({
2   claimType: "age_over18_united_kingdom",
3 });

Arguments — IssuePrivacyPassParams

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

Returns — IssuePrivacyPassResponse

Field	Type	Description
`privacyPassToken`	`string`	The issued Privacy Pass token. Hold this server-side and pass to `generateClaim` once the user completes verification

`generateClaim`

Redeems the Privacy Pass token against Persona and returns the claim payload.

Node.js

Go

1 const claim = await persona.relays.generateClaim({
2   privacyPassToken,
3   relayToken: session.relayToken,
4   relaySecret: session.relaySecret,
5 });

If you created the relay session with an encryptionKeyPem, claimPayload will be a base64-encoded RSA-OAEP ciphertext. Decrypt it with your corresponding private key.

Arguments — GenerateClaimParams

Field	Type	Required	Description
`privacyPassToken`	`string`	true	The Privacy Pass token from `persona.relays.issuePrivacyPass`
`relayToken`	`string`	true	The relay token from `persona.relays.create`
`relaySecret`	`string`	true	The relay secret from `persona.relays.create`

Returns — GenerateClaimResponse

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

Error handling

Node.js

Go

1 import { PersonaError, BadRequestError, RateLimitedError } from '@persona/sdk-node';
2 
3 try {
4   const claim = await persona.relays.generateClaim({ ... });
5 } catch (err) {
6   if (err instanceof RateLimitedError) {
7     // retry with backoff
8   } else if (err instanceof PersonaError) {
9     console.error(err.statusCode, err.title, err.details);
10   }
11 }

All Persona API errors and network failures throw a subtype of PersonaError.

Property	Type	Description
`statusCode`	`number`	HTTP status code from the Persona API
`title`	`string`	Short description of the error
`details`	`string \| undefined`	Optional longer description
`code`	`string \| undefined`	Optional machine-readable error code
`meta`	`Record<string, unknown> \| undefined`	Optional additional metadata

See Error responses for the raw JSON error shape returned by the API.