Agent keys are the credential that authorizes your agents’ spending, so their lifecycle deserves the same care as your API keys. This page explains how keys are generated inside SohoPay’s MPC infrastructure, how rotation and disaster recovery work, and the operational practices we recommend for production operators.

​
How agent keys work

When you create an agent, its key is generated inside SohoPay’s MPC signing infrastructure as a 2-of-3 threshold key. The three shares are:
  1. Agent share — used to sign on the agent’s behalf.
  2. Policy Service share — held by the Policy Service, which co-signs only after every payment passes allowlist, credit, rate-limit, and AML checks.
  3. Third-party share — a future third key on the roadmap; today the third slot is the cold backup share (see disaster recovery below).
Two properties follow from this design:
  • You never receive a raw private key. The complete key never exists in one place — not at generation, not during signing, not in any API response. There is nothing for you to store, leak, or commit to git.
  • No single share can spend. A payment signature requires 2-of-3, and the Policy Service share only participates after policy checks pass. If the Policy Service is unavailable, no settlements happen — the system fails closed.
Key operations run on AWS KMS today; OpenSigner with Shamir secret sharing is on the roadmap.
Your operational burden is the API key (sk_test_... / sk_live_...), not the agent key. Anyone with your API key can create orders and submit payments for your agents, so protect it as described in Authentication & Security.

​
Key rotation

Rotation generates fresh MPC shares for an agent and retires the old ones. The agent’s wallet_address and agent_id are unchanged — rotation is invisible to merchants and to in-flight orders. Rotate when:
  • A team member with production access leaves.
  • You suspect any compromise of the systems that call the SohoPay API for this agent.
  • Your security policy mandates periodic rotation.
Today, rotation is performed from the Dashboard (Agents → select agent → Rotate key) or by contacting support.
A self-serve POST /agents/{agent_id}/rotate endpoint is on the roadmap and not yet available. Until it ships, use the dashboard or support@sohopay.xyz for rotations.
When rotation completes, SohoPay delivers an agent.key_rotated webhook:
agent.key_rotated
Verify the event signature as described in Webhooks and alert your on-call channel — a rotation you didn’t initiate is a security signal.

​
Disaster recovery

The third key slot holds a cold backup share kept in escrow, offline and outside the hot signing path. If the agent share or the Policy Service share is lost or corrupted, the cold share restores the 2-of-3 quorum so the wallet’s funds and credit position are never stranded behind a single lost share. Recovery is operated by SohoPay under a documented runbook:
  1. You (or SohoPay’s monitoring) report a suspected share loss to support — critical issues get an under-1-hour response per the SLA.
  2. SohoPay pauses the affected agent, so no payments sign during recovery.
  3. The cold share is brought online in a controlled ceremony, the quorum is re-established, and fresh shares are generated (a forced rotation).
  4. You receive an agent.key_rotated webhook and the agent is unpaused.
Recovery never hands you a raw private key. If anyone claiming to be SohoPay asks you to receive, store, or transmit key material, treat it as phishing and report it to support@sohopay.xyz.

​
Security attestation

An independent audit of the MPC signing infrastructure and vault contracts by Olympix is in progress and not yet published. SohoPay is pre-mainnet; the report will be linked from this page when available. SOC 2 is planned post-launch — see the roadmap items in Trust Model.

​
Best practices

A short checklist for production operators:
  • Rotate on personnel change. Any time someone with production API access or dashboard admin rights leaves, rotate affected agents’ keys and your API keys the same day.
  • Monitor agent.key_rotated events. Every rotation should map to a change ticket you recognize. Alert on ones you can’t match.
  • Pause the agent before a planned rotation. Pausing from the dashboard drains in-flight payments cleanly, so nothing is signing mid-rotation. Unpause after the agent.key_rotated event arrives.
  • Keep limits tight. daily_limit is your real blast-radius control — key compromise plus a tight daily limit is an incident; key compromise plus an open limit is a loss. See Agent Setup.
  • Separate sandbox and mainnet credentials. Different keys, different secret-manager entries, different IAM access.
  • Log request_id on every API call so support can trace any suspicious signing activity quickly.

​
Next steps

MPC Signing

The 2-of-3 threshold scheme in protocol-level detail.

Webhooks

Verify signatures and handle agent.key_rotated events.

Vault & Funding

Fund the vault that backs your agents’ credit lines.