Bringing your own encryption key
A Relay claim result is built to hold as little as possible. It says whether a claim passed or failed, and sometimes which method produced it. There is no name, birthdate, or document in it, and Persona deletes the verification data behind it once the result exists.
You can add a further layer on top of that. When you create a Relay session, you can supply your own public key, and Persona encrypts the claim payload with it before returning it, so only the holder of the matching private key can read the result.
Persona recommends it. Relay exists to keep personal data out of places it does not need to be, and encrypting the payload extends that to the result itself.
Whether to use it is your decision. Supply a key and the payload comes back encrypted. Send null for the key field and it comes back as plain JSON.
What it adds
Encrypting the payload narrows who can read a claim result to exactly one system, the one holding your private key. The result stays unreadable anywhere it might otherwise sit in the clear, including in a log, a proxy, or an intermediate service inside your own infrastructure.
That matters most if the response passes through anything on its way to the system that makes the access decision. If you have a gateway, a service mesh, or a logging layer in between, encrypting the payload keeps the result out of all of them.
This is a good decision to make before you launch rather than after. Turning it on later means changing how your server reads every claim result.
How it works
- You generate an asymmetric key pair and keep the private key on your server.
- You pass the public key when you create the Relay session, as a JWK in
encryption-key-jwk(recommended). - When you redeem the claim, the payload comes back as ciphertext rather than JSON.
- Your server decrypts it with the private key and reads the result.
Persona only ever receives the public half, so Persona cannot read the encrypted payload it produced.
Every Relay session needs one key field, encryption-key-jwk or encryption-key-pem. To skip encryption, send null for it. The payload is then returned as plain JSON and no decryption step is needed. That is the simpler path for a first integration, and switching to your own key later is a change on your side only.
Choosing a key format
Use encryption-key-jwk for new integrations. Persona returns the claim as a compact JWE message, encrypted with RSA-OAEP-256 for the key and A256GCM for the content. Your server decrypts it with any standard JOSE library and the matching private key.
encryption-key-pem is deprecated, and a future API version will reject it. It still works today, and claims encrypted with it return claim-payload-encryption as rsa_oaep. If you use it, move to encryption-key-jwk. PEM encryption also limits the payload to about 214 bytes for a 2048-bit key, which is too small for larger claims.
Send exactly one non-null key field per Relay session. The claim-payload-encryption field in the generated claim tells you which scheme was used: jwe, rsa_oaep, or none.
JWK requirements
The JWK must be an RSA public key with these properties:
ktyisRSAandalgisRSA-OAEP-256. A missing or differentalgis rejected.nandeare present, and the key is 2048 to 4096 bits.eis odd and at least 65537 (AQAB). A smaller exponent such asAwis rejected.- It contains no private members (
d,p,q,dp,dq,qi,oth). use, if present, isenc.key_ops, if present, includesencryptorwrapKey.
If it does not work
- A 400 response about the JWK when you create the session. The key is invalid. Check it against the requirements above. An empty
{}, a missingalg, a smalle, or a JWK with private members is rejected. Persona never falls back to a plain payload for a key you sent. - A 400 response about the key fields when you create the session. You sent both
encryption-key-jwkandencryption-key-pemwith values, or you sent neither. Send one key field. To skip encryption, sendnullfor it. - The payload comes back as plain JSON. You sent
nullfor the key field, which opts out of encryption. Send a key instead. - Your server cannot decrypt the payload. Confirm the private key matches the public key you sent, and that your library supports RSA-OAEP-256 with A256GCM.
Full technical documentation
The developer documentation is the source of truth for the field name, the encoding, and the decryption samples:
Plans Explained
Claim payload encryption by plan
| Startup Program | Essential Plan | Growth Plan | Enterprise Plan | |
|---|---|---|---|---|
| Claim payload encryption | Available | Available | Available | Available |