VORIM
We use cookies

We use cookies to analyze site traffic and improve your experience. You can choose to accept all cookies or only essential ones. See our Privacy Policy.

Customer mandates and the bank gateway check

Let a customer sign, on their own phone, what an agent may do for them. Every action is checked against those limits, the customer can withdraw with the same key, and a bank can check an outside agent before serving it.

Customer mandates

A mandate is what a customer allowed an agent to do for them: which actions, up to what amount each and in total, how many times, until when. The customer signs it with a key on their own device. A phone's secure hardware (iPhone Secure Enclave, Android StrongBox) holds P-256 keys, so mandates take ES256 as well as EdDSA. Vorim only ever receives the public key.

// 1. Your app creates the mandate with the customer's PUBLIC key
const { mandate, signing_input } = await vorim.createMandate({
  agentId, customerRef: "cust_7731", alg: "ES256", publicKeyJwk: phonePublicJwk,
  terms: { actionTypes: ["initiate_payment"], maxAmount: 5000, currency: "GBP", maxTotal: 20000, maxUses: 10 },
  expiresAt: new Date(Date.now() + 30 * 86400e3).toISOString(),
});

// 2. The customer's phone signs signing_input (CryptoKit SecureEnclave.P256 or Android Keystore)
//    and your app sends the signature back. Vorim verifies it and countersigns a record.
await vorim.activateMandate(mandate.mandate_id, signatureFromPhone);

// 3. The agent names the mandate on every action it takes for that customer
const d = await vorim.beforeAction({
  agentId, actionType: "initiate_payment", payload: { amount: 4000, currency: "GBP" },
  mandateId: mandate.mandate_id, caseRef: "cust_7731",
});
typescript
c = v.create_mandate(agent_id, "cust_7731", "ES256", phone_public_jwk,
                     {"action_types": ["initiate_payment"], "max_amount": 5000, "currency": "GBP", "max_total": 20000},
                     expires_at)
v.activate_mandate(c["mandate"]["mandate_id"], signature_from_phone)
v.before_action(agent_id, "initiate_payment", payload={"amount": 4000, "currency": "GBP"},
                mandate_id=c["mandate"]["mandate_id"])
python
  • An action outside the mandate is refused, and the reason names each limit it broke, in money (for example "£60.00 is over the £50.00 limit for one payment").
  • An allowed or escalated amount is charged against the total in one step, so two actions at the same moment cannot both fit under the last of the allowance. If a person refuses an escalated action, or no one answers in time, the charge is given back.
  • A mandate that names a money limit refuses a payment that carries no amount. A read (GET or HEAD) needs none.
  • ES256 signatures may be the raw 64-byte r||s (CryptoKit rawRepresentation) or DER (Android Keystore), base64url. Passkeys and App Attest keys sign through their own formats (below).
  • Without a hardware proof (below), the signed record says key_attestation: "none"; never describe such a mandate as hardware-backed.

Prove the key is in secure hardware

Ask for a one-time challenge, have the device bake it into a key attestation, and pass the attestation when you create the mandate. Vorim checks it against the platform's own root and records the level it proved on the signed record.

const { challenge } = await vorim.getAttestationChallenge();   // one use, 10 minutes
// Android: KeyGenParameterSpec.Builder(...).setAttestationChallenge(challenge.toByteArray())
//          (setIsStrongBoxBacked(true) where the phone has StrongBox), then keyStore.getCertificateChain(alias)
await vorim.createMandate({ ...mandate, alg: "ES256", publicKeyJwk,
  keyAttestation: { format: "android-key", certificateChain: chainBase64LeafFirst, challenge } });

// iPhone: DCAppAttestService.attestKey(keyId, clientDataHash: SHA256(challenge)); the key then signs only
// through generateAssertion(keyId, clientDataHash: SHA256(text)), so activation takes an assertion:
await vorim.createMandate({ ...mandate, alg: "ES256", publicKeyJwk,
  keyAttestation: { format: "apple-app-attest", attestationObject, keyId, appId: "TEAMID.com.bank.app", environment: "production", challenge } });
await vorim.activateMandate(id, { format: "app-attest", assertion: assertionBase64 });

// Passkey in a browser or app: the challenge is base64url(SHA-256(signing_input))
await vorim.createMandate({ ...mandate, alg: "ES256", publicKeyJwk, webauthn: { rpId: "bank.example", origin: "https://bank.example" } });
await vorim.activateMandate(id, { format: "webauthn", authenticator_data, client_data_json, signature });
typescript
  • Android: the chain must end in a Google attestation root (including the P-384 root used from February 2026), every link must verify, no certificate may be on Google's revocation list, and the key must be in a Trusted Execution Environment or StrongBox. The record says which.
  • iPhone (App Attest): the chain must end in Apple's App Attestation root; the nonce, key id, App ID, counter and environment are checked as Apple documents. Every later signature is an assertion whose counter must rise, so one cannot be replayed.
  • Passkeys: the passkey's own flags say whether it may be synced to other devices. A synced passkey is recorded as passkey-synced: it shows the customer's account approved, not one particular phone.
  • These checks follow Google's and Apple's documentation and are tested against certificate chains built for the purpose; they have not yet been run against every phone model. Google recommends its own verification library for Android; Vorim's is a separate implementation of the same steps.

AP2 (Agent Payments Protocol)

A Vorim mandate maps onto an AP2 v0.2 open Payment Mandate: the per-payment limit becomes payment.amount_range, the total payment.budget, the use count payment.agent_recurrence, exact payees payment.allowed_payees, and the customer's key cnf.jwk. Export one for a merchant or credential provider that speaks AP2, or import one your own trusted surface issued.

const { sd_jwt, not_expressed_in_ap2 } = await vorim.exportMandateAp2(mandateId);   // signed by Vorim (EdDSA)

const imported = await vorim.importAp2Mandate({ sdJwt, issuerJwk, agentId, customerRef: "cust_7731" });
// pending until the customer's key (cnf.jwk) signs imported.signing_input
typescript

An import is refused when the issuer signature does not verify, and when a constraint asks for something Vorim does not enforce (payment instruments, payment initiation providers, execution dates, a link to a checkout, recurring periods other than on demand). A limit the customer set is never dropped silently.

The customer withdraws, with their own key

No Vorim account is involved: the signature is the credential. Sign the withdrawal line on the device within five minutes of sending it.

import { mandateWithdrawalLine } from "@vorim/sdk";
const signedAt = new Date().toISOString();
const line = mandateWithdrawalLine(mandateId, signedAt);   // "vorim-mandate-withdraw|v1|<id>|<signedAt>"
await vorim.withdrawMandate(mandateId, signedAt, await phoneSign(line));
typescript

Evidence for a bank or an ombudsman

getMandateEvidence(id) returns the record Vorim countersigned at activation (the mandate, the customer's signature and public key) and every decision taken under it. Anyone can check both signatures offline, or post the record to POST /v1/evidence/verify.

The bank gateway check

For a bank deciding whether to serve an outside agent. The agent signs its request with RFC 9421 HTTP message signatures (vorim.signHttpRequest). The bank's API edge forwards the method, URL and headers with the mandate id. Vorim checks that the signature is the agent's and not a replay, that the agent is still active, and that the request sits inside a mandate signed by this customer. It returns a sealed verdict the bank keeps. An allowed payment is charged against the mandate.

// On the bank's side, with the bank's own Vorim API key (scope runtime:decide)
const v = await bankVorim.gatewayCheck({
  request: { method: req.method, url: fullUrl, headers: req.headers },
  mandateId: req.headers["x-vorim-mandate"], customerRef: bankCustomerRef,
  actionType: "initiate_payment", amount: 4000, currency: "GBP",
});
if (v.payload.verdict !== "allow") return refuse(v.payload.reasons);
typescript

Vorim decides; it does not proxy the request or see the bank's response. The gateway has not yet run with a bank.

Drop-in for nginx and Envoy

Your gateway can ask Vorim directly, with no code: nginx with auth_request, Envoy with its ext_authz HTTP filter, both pointed at /v1/gateway/authz. Vorim answers 204 to serve or 403 to refuse, with X-Vorim-Verdict-Hash for your logs and X-Vorim-Reasons on a refusal. Your Vorim key travels in X-Vorim-Key, so the agent's own headers reach the signature check exactly as it signed them.

location /agent-api/ {
    auth_request /_vorim_check;
    auth_request_set $vorim_verdict_hash $upstream_http_x_vorim_verdict_hash;
    proxy_pass http://your-api;
}
location = /_vorim_check {
    internal;
    proxy_pass https://api.vorim.ai/v1/gateway/authz;
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";
    proxy_set_header X-Original-Method $request_method;
    proxy_set_header X-Original-URL "https://api.bank.example$request_uri";
    proxy_set_header X-Vorim-Key "agid_sk_...";   # runtime:decide; keep it out of git
}
nginx

Because nginx does not forward the body, Vorim requires the agent's signature to cover X-Vorim-Mandate and, when sent, X-Vorim-Amount, X-Vorim-Currency and X-Vorim-Action; an uncovered header is refused. The nginx config in the repository (examples/bank-gateway) was tested against nginx 1.31.7; the Envoy one has not yet run against a live Envoy. Once your gateway has served an agent, its suspension and revocation also reach your Shared Signals streams for 90 days.

Need Help?

Book a demo for a walkthrough, or contact us for support. For enterprise needs, reach out at sales@vorim.ai.