Request4R (JWE encrypted channel)

When Request4R is enabled for your tenant, you can call the same Partner operations through a dedicated URL prefix. Request bodies are compact JWE strings instead of raw JSON; JSON responses may be returned as JWE with Content-Type: application/jose. Your api_key header is unchanged.

Enablement, base URLs, and key exchange are coordinated with Leap integration. Do not assume Request4R is active in production until your tenant is explicitly configured.

When to use it

You need payload confidentiality at the application layer (in addition to HTTPS).
Your backend can produce and consume compact JWE (e.g. with the jose library).

Concepts

Item	Details
URL prefix	Use `{BASE}/v1/partners/request4r` instead of `{BASE}/v1`. The path after the prefix mirrors the standard Partner route (e.g. `.../request4r/auth/register-user-v2` ↔ `.../v1/auth/register-user-v2`).
Algorithms	Key encryption: RSA-OAEP-256. Content encryption: A256GCM. Format: compact JWE (RFC 7516).
Requests (you → RaaS)	Plaintext is UTF-8 JSON (same schema as OpenAPI). Encrypt with the RaaS public key (SPKI PEM provided by Leap).
Responses (RaaS → you)	When encryption applies, the body is a compact JWE string and `Content-Type: application/jose`. Decrypt with your partner private key (PKCS#8) that matches the partner public key registered with Leap.
Correlation	Include `reference_id` (string) in the JSON plaintext when you need tracing; the gateway may surface `X-Reference-ID` downstream.

Key exchange

Request4R uses two separate RSA key pairs—one owned by RaaS (Leap) and one owned by the partner. Payload encryption always follows the same rule:

Encrypt with the recipient’s public key. Decrypt with your own private key.

This is standard asymmetric encryption for confidentiality. It is not digital signing (you do not encrypt with a private key and decrypt with a public key).

Direction	Who encrypts	Key used to encrypt	Who decrypts	Key used to decrypt
Request (partner → RaaS)	Partner	RaaS public (SPKI PEM from Leap)	RaaS	RaaS private (held by Leap only)
Response (RaaS → partner)	RaaS	Partner public (SPKI you register with Leap)	Partner	Partner private (PKCS#8; never share with Leap)

What each party holds

Party	Keep secret (never share)	Share with the other party
Partner	Partner private key (PKCS#8)	Partner public key (SPKI)
RaaS (Leap)	RaaS private key (PKCS#8)	RaaS public key (SPKI)

During onboarding, Leap provides your tenant the RaaS public key for encrypting requests. You generate a partner key pair, keep the private key on your backend, and send Leap only the public key so RaaS can encrypt responses to you.

Run all JWE operations on your server. Partner private keys must not ship to browsers, mobile apps, or client-side SDKs.

Authentication

Send api_key on every request, identical to the standard Partner API (Authentication). Request4R wraps the body only; it does not replace tenant authentication.

Building a request

Build the same JSON body documented in OpenAPI for the underlying route.
Encrypt the UTF-8 JSON string to compact JWE using the RaaS SPKI and headers alg: RSA-OAEP-256, enc: A256GCM.
HTTP: use the same method (POST, PUT, PATCH, …). Put the single-line JWE in the body. Use a text-friendly Content-Type (e.g. text/plain) unless Leap specifies otherwise for your environment.

Reading a response

If Content-Type: application/jose, RaaS encrypted the JSON with your partner public key (the SPKI you registered). Decrypt the body with your matching partner private key, then parse UTF-8 plaintext as JSON (same response shapes as the standard endpoint).
With sandbox-only X-Skip-Encryption (see below), responses may remain application/json.

Sandbox and testing

X-Skip-Encryption disables payload encryption for internal or sandbox testing only. Do not send this header from production clients.

If this header is present (any value):

Send Content-Type: application/json and a normal JSON body.
Responses may stay JSON instead of JWE.

Errors

Invalid or undecryptable bodies typically return 400 with a stable code such as ERROR_INVALID_JWE_PAYLOAD and a short reason—not stack traces.

Example (Node.js + `jose`)

Run crypto only on your backend. Do not ship partner private keys to browsers or mobile apps.

import { readFile } from "fs/promises";
import { CompactEncrypt, compactDecrypt, importPKCS8, importSPKI } from "jose";

// Encrypt request (RaaS SPKI from Leap)
const raasPublicPem = await readFile("raas-request4r-public.pem", "utf8");
const payload = JSON.stringify({ reference_id: "your-ref" /* …fields per OpenAPI… */ });
const encKey = await importSPKI(raasPublicPem.trim(), "RSA-OAEP");
const jwe = await new CompactEncrypt(new TextEncoder().encode(payload))
  .setProtectedHeader({ alg: "RSA-OAEP-256", enc: "A256GCM" })
  .encrypt(encKey);

// POST `jwe` as raw body to …/v1/partners/request4r/… with header api_key

// Decrypt response (partner PKCS#8)
const partnerPrivatePem = await readFile("partner-request4r-private.pem", "utf8");
const decKey = await importPKCS8(partnerPrivatePem.trim(), "RSA-OAEP");
const { plaintext } = await compactDecrypt(responseBodyString, decKey);
const json = JSON.parse(new TextDecoder().decode(plaintext));

Checklist for integrators

Confirm enablement

Verify with Leap that Request4R is on for your tenant and environment (sandbox vs production).

Keys

Generate a partner RSA key pair. Give Leap your partner public (SPKI). Store RaaS public (encrypt requests) and partner private (decrypt responses) on your backend only. Rotate only with Leap guidance.

Route mapping

Map each call from /v1/... to /v1/partners/request4r/... with the same method and decrypted JSON schema.

Operations

Use reference_id for reconciliation when your product requires it.

Authentication
Testing & sandbox
Partner OpenAPI — schemas are unchanged once payloads are decrypted.

Questions or key onboarding: your Leap integration contact or support@leapfinancial.com.

Getting Started

Guides

When to use it

Concepts

Key exchange

What each party holds

Authentication

Building a request

Reading a response

Sandbox and testing

Errors

Example (Node.js + `jose`)

Checklist for integrators

​When to use it

​Concepts

​Key exchange

​What each party holds

​Authentication

​Building a request

​Reading a response

​Sandbox and testing

​Errors

​Example (Node.js + jose)

​Checklist for integrators

​Related

When to use it

Concepts

Key exchange

What each party holds

Authentication

Building a request

Reading a response

Sandbox and testing

Errors

Example (Node.js + `jose`)

Checklist for integrators

Related