Skip to navigation
API ReferenceRelay

Generate a Relay claim

Returns a relay's claim.

Authentication

AuthorizationPrivateToken token=

Privacy Pass token per RFC 9577. Provide as Authorization: PrivateToken token=<privacyPassToken>.

Path parameters

relay-tokenstringRequired

The public Relay token returned by POST /relays.

Headers

Key-InflectionenumOptional
Determines casing for the API response.
Allowed values:
Idempotency-KeystringOptional
Ensures the request is idempotent.
Persona-VersionenumOptional

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

Persona-Relay-SecretstringRequired

The relay-secret value returned at Relay creation. Required for every read of the claim payload; an incorrect secret returns 404.

Response headers

RateLimit-LimitintegerOptional

The maximum number of requests permitted in the current rate limit window. For an API key with its own rate limit, requests count against both the key’s limit and the environment’s limit, and this header reports whichever is closer to being reached, so it can change between responses. On a 429 response, it reports the limit that rejected the request. For an API key without its own rate limit, it reports the environment’s limit. Returned on every authenticated response.

RateLimit-RemainingintegerOptional

The number of requests remaining in the current rate limit window for the limit reported in RateLimit-Limit. Returned on every authenticated response.

RateLimit-ResetintegerOptional
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 claim payload and whether the Privacy Pass token was consumed.
claim-payloadstring

The claim payload. If an encryption-key-jwk was provided at Relay creation, this is a compact JWE (RSA-OAEP-256 / A256GCM). If an encryption-key-pem was provided, this is a base64-encoded RSA OAEP (SHA-1) ciphertext. Either must be decrypted client-side. Otherwise, this is a JSON string containing claim_type, claim_result, and an optional methodology array.

claim-payload-encryptionstring

How claim-payload is encrypted. Possible values:

  • jwe: compact JWE, from encryption-key-jwk
  • rsa_oaep: base64 RSA OAEP (SHA-1) ciphertext, from encryption-key-pem
  • none: unencrypted JSON string

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

token-consumedboolean

true if the Privacy Pass token was consumed by this request. false if the underlying claim did not pass and the token was refunded to the client.

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