Skip to navigation
API ReferenceRelay

Request a Relay challenge

Requests a Privacy Pass challenge for a claim type. The challenge materials returned here are used to obtain a Privacy Pass token, which is then redeemable to read claims from Relays with the same claim type.

Headers

Key-InflectionenumOptional
Determines casing for the API response.
Allowed values:
Persona-VersionenumOptional

Server API version. More info on versioning can be found here.

Request

This endpoint expects an object.
claim-typestringRequired

Possible values:

  • live_human_presence
  • age_over18_germany
  • age_over18_united_kingdom
  • age_over18_verified
  • age_over18_france
  • age_over18_italy
  • age_over18_brazil
  • age_over18_australia
  • age_over16_australia
  • age_over21_verified

Do not assume this is a static enumeration; Persona may add new claim types in the future without a versioned update.

sandboxbooleanOptional

When true, Persona issues a sandbox-namespace challenge, redeemable only against sandbox Relays. When omitted or false, Persona issues a challenge for the claim-type namespace.

Response headers

RateLimit-Limitinteger
The maximum number of requests permitted in the current rate limit window for the API key used to authenticate the request. Returned on every authenticated response.
RateLimit-Remaininginteger
The number of requests remaining in the current rate limit window for the API key used to authenticate the request. Returned on every authenticated response.
RateLimit-Resetinteger
The number of seconds until the current rate limit window resets. Returned on every authenticated response.
Request-IdstringOptional

The unique identifier of the API log entry that recorded this request. Starts with req_. Include this value when reaching out to Persona support. Present on every authenticated response, including error responses.

Persona-Environment-IdstringOptional
The token of the Persona environment that handled the request. Returned on every authenticated response, including most error responses.
Persona-Organization-IdstringOptional
The token of the Persona organization that handled the request. Returned on every authenticated response, including most error responses.

Response

Returns the Privacy Pass challenge materials for the requested claim type.
challengestring

base64url-encoded PrivateToken challenge object (RFC 9577). Pass this to the Privacy Pass issuance flow to obtain a token.

token-keystring

base64url-encoded DER public key used to issue the token.

token-key-idstring

hex-encoded SHA-256 of token-key.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
422
Unprocessable Entity Error
429
Too Many Requests Error