Skip to main content
This page is the architectural reference for what you can and cannot do with each kind of credential. Read it before designing your integration — the wrong assumption here is a security incident.

​
The guarantee

Relayer never holds keys that anyone at Relayer can use without your explicit authorization. The cryptographic authority to sign always lives in one of two places:
  • Your wallet stack — MPC, HSM, MetaMask, Phantom, Fireblocks, Privy server-side. You picked it; you sign with it.
  • A hardware enclave (HSM) gated by your passkey — Relayer/Turnkey runs the infrastructure, but the key material is inert without a WebAuthn stamp from your registered passkey. Nobody at Relayer can use it.
In the second case, the keys physically reside on Relayer-managed infrastructure, but they are functionally self-custodial: no Relayer employee, no rogue code, no compromised server can move funds. The only thing that can authorize signing is the passkey on your (or your user’s) device. This is the distinction between custody (someone else can move your funds) and enclave-hosted self-custody (only your passkey can move your funds, even though Relayer runs the enclave).

​
The two dimensions

Every signing decision is the product of two choices:

​
Dimension 1 — Who holds the key?

​
Dimension 2 — What’s the scope of pre-authorization?

​
The combinations

There is no scenario where Relayer holds custody in the legacy sense. There is no scenario where someone at Relayer can move user funds.

​
What each credential type can do

The API supports three credential types. Each is necessary but not always sufficient.

​
Authorization: ApiKey rk_client_key_v1_...

Backend integrations. Issued from the dashboard, scoped (integrator / integrator:read / integrator:write). The recurring pattern: ApiKey can prepare, configure, and observe — but the act of signing is always gated by a passkey or by an agent’s HMAC.

​
X-Agent-Auth HMAC headers

Agent SDK runtime. HMAC-SHA256 signature derived from the agent secret issued at provisioning time. The agent’s authority is whatever the human granted at provisioning time, bounded by policies + budgets. The HMAC secret doesn’t grant cryptographic authority — it proves identity. The actual authorization comes from the policies signed by a human passkey when the agent was created.

​
Passkey (WebAuthn)

The cryptographic root of all signing authority for enclave-hosted wallets. Lives on the user’s device (Face ID, Touch ID, hardware security key, Windows Hello). The passkey is the only thing that can authorize signing. Everything else — ApiKey, HMAC, JWTs — is identity or session, not authority.

​
When you need a human passkey, period

No matter what mode you’re in, a transaction above approvalThresholdUSDC requires a human to stamp it with a passkey. That’s not a limitation — it’s the design. If you want a higher autonomy ceiling, raise the threshold consciously. If you want a kill switch on autonomy, lower it. For Agent Kit specifically, the approval response is HTTP 202 with an approvalId. The SDK polls until resolution (default 5-minute timeout, configurable). For raw API calls, you implement the same polling pattern manually.

​
Off-ramp specifically

A common question: can my off-ramp run 100% backend, no humans? The off-ramp flow has 4 steps:
  1. Setup (/payout/accounts/setup/*, /payout/recipients/*) — ApiKey only ✅
  2. Move stablecoins to the withdrawal address — depends on who signs that on-chain transfer ⬇
  3. Trigger settlement (/payout/accounts/execute) — ApiKey only ✅
  4. Fiat to recipient bank — handled by the rails partner, out of band
Step 2 is the question. Three patterns:
  • Your wallet stack signs the on-chain transfer → fully backend ✅
  • Agent Kit with policies that allow transfers to the withdrawal address → fully backend within bounds ✅
  • End-user passkey wallet signs the transfer per-tx → user must be present ❌
There is no scenario where Relayer prevents you from a backend-only off-ramp — it depends on your key-holder model, not on us.

​
How to choose your model

You hold the keys (your wallet stack)

When: you already have MPC, HSM, or sufficient signing infrastructure; you want maximum control; you don’t want end-users in the loop. Use: ApiKey for everything Relayer does; sign on-chain transactions with your own stack.

Agent Kit (delegated, integrator-owned)

When: you want backend automation but don’t want to run signing infrastructure; budget and policy boundaries are sufficient governance. Use: provision agents via passkey ceremony (one-time), then HMAC at runtime.

Per-end-user passkey wallets

When: end-users own their funds; each user is in the loop for every transaction; consumer-facing UX. Use: Widget Kit Passkey Signing. Each end-user enrolls a passkey; each transaction prompts biometrics.

Hybrid (passkey + agent)

When: end-users want autonomous helpers acting on their behalf within bounds. Use: end-user enrolls passkey + grants policies → agent operates with HMAC within those bounds. Above threshold → user stamps.

​
Common mistakes to avoid

Mistake 1: Treating ApiKey as authority. ApiKey lets you administer; it does not let you sign. If your backend needs to move funds, you need to either (a) hold your own keys, (b) run an agent, or (c) involve a user with a passkey.
Mistake 2: Confusing “Relayer hosts the enclave” with “Relayer holds custody”. The enclave hosts the key material; the passkey on the user’s device is the only thing that can use it. Relayer cannot move funds, period.
Mistake 3: Setting approvalThresholdUSDC to a large number “to avoid friction”. That removes the human gate on large transactions — exactly the case where you want human confirmation. Default low; raise only with eyes open.
Mistake 4: Building a flow that assumes ApiKey can complete a confirm step. The prepare/confirm split is intentional: prepare returns an activity, the passkey stamps it, confirm submits the stamped result. There is no shortcut.

​
See also

Authentication

Header formats, key scopes, HMAC payload spec, and code snippets per language.

Architecture

How the Kits fit together and where each credential type is accepted.

Signing Kit

The prepare/confirm flow in detail — and why it exists.

Agent Kit

Bounded delegation: passkey-stamped provisioning, HMAC at runtime.