Key Management

Agent keys are the credentials that authorize your autonomous agents’ on-chain payments. This guide covers how agent keys operate within SohoPay’s 2-of-3 threshold infrastructure, how to perform zero-downtime key rotations, and how emergency revocations function.

The 2-of-3 MPC architecture

When an operational agent is provisioned, its cryptographic identity is generated inside SohoPay’s MPC signing infrastructure as a 2-of-3 threshold key. The three shares are distributed as follows:

                  ┌─────────────────────────────────────────┐
                  │          2-of-3 Threshold Signing       │
                  └────────────────────┬────────────────────┘
                                       │
        ┌──────────────────────────────┼──────────────────────────────┐
        ▼                              ▼                              ▼
┌──────────────┐               ┌──────────────┐               ┌──────────────┐
│   Share 1    │               │   Share 2    │               │   Share 3    │
│Agent Workload│               │Policy Service│               │ Cold Backup  │
│  (Ephemeral) │               │ (Gatekeeper) │               │   (Escrow)   │
└──────────────┘               └──────────────┘               └──────────────┘

Agent Workload Share: Held locally by the agent runtime or MPC escrow to sign payment requests with Proof-of-Possession (PoP).
Policy Service Share: Held by SohoPay’s Policy Service. It co-signs only after validating spend limits, available credit, merchant allowlists, and sanctions screening.
Cold Backup Share: Stored offline in secure escrow for disaster recovery.

Key security properties

Zero raw private key exposure: The full private key is never assembled in any single memory space, database, or API response. There is no raw private key to leak or commit to version control.
Fail-closed security: Neither share can sign a transaction alone. If the Policy Service detects a policy violation or becomes unreachable, payment authorization fails closed.
Persistent wallet address: The agent’s Base wallet_address and agent_id remain identical across key rotations.

How to rotate agent keys

Key rotation generates a fresh key share pair and retires the previous shares. In-flight orders and merchant allowlists are completely unaffected. Rotate agent keys:

Whenever an engineer or operator with access leaves your organization.
If you suspect any environment or runtime vulnerability.
As part of your regular compliance schedule (e.g. quarterly).

Method A: Via the Borrower Portal (Recommended)

Sign in to the SohoPay Borrower Portal.
Navigate to My Agents and select the agent.
Click Rotate Key and confirm the prompt with your connected wallet signature.

Method B: Programmatic rotation via Gateway API

For autonomous platform operators, SohoPay provides a multi-step off-chain rotation protocol:

Step 1: Initiate key rotation (PoP)

The agent runtime submits its new public key (JWK) along with a Proof-of-Possession (pop_signature):

curl -X POST https://staging.api.sohopay.xyz/api/v1/agents/agt_3f9a1c8e/key-rotations \
  -H "Authorization: Bearer $SOHOPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "borrower_id": "usr_sandbox_operator_01",
    "public_jwk": {
      "kty": "OKP",
      "crv": "Ed25519",
      "x": "base64url_public_key_value"
    },
    "jkt": "thumbprint_hash",
    "nonce": "unique_nonce_12345",
    "iat": 1727788800,
    "pop_signature": "signature_hex"
  }'

Step 2: Check rotation status & fetch challenge

Poll the rotation status to retrieve the EIP-712 challenge:

curl https://staging.api.sohopay.xyz/api/v1/agents/agt_3f9a1c8e/key-rotations/rot_7b8c9d0e \
  -H "Authorization: Bearer $SOHOPAY_API_KEY"

Step 3: Reauthorize with operator wallet signature

The operator signs the EIP-712 challenge with their external wallet:

curl -X POST https://staging.api.sohopay.xyz/api/v1/agents/agt_3f9a1c8e/key-rotations/rot_7b8c9d0e/reauthorize \
  -H "Authorization: Bearer $SOHOPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "signature": "0x_operator_eip712_signature_hex"
  }'

Webhook notification: `agent.key_rotated`

Upon successful rotation, SohoPay delivers an agent.key_rotated event to your registered webhook endpoint:

{
  "event_id": "evt_2b8c4d1a",
  "type": "agent.key_rotated",
  "created_at": "2026-08-22T14:03:11Z",
  "data": {
    "agent_id": "agt_3f9a1c8e",
    "wallet_address": "0x8ba1f109551bd432803012645ac136ddd64dba72",
    "rotated_at": "2026-08-22T14:03:10Z"
  }
}

Verify the Sohopay-Signature header as documented in Webhook Verification.

Emergency agent revocation (Kill Switch)

Understanding the distinction between pausing and revoking is critical for incident response:

State	Gateway Impact	Recoverable?	Description
Pause	All new payment authorizations rejected	Yes (Instant Resume)	Temporary freeze for maintenance or limit reviews.
Revoke	Key shares destroyed permanently	No (Irreversible)	Permanent deauthorization. The agent cannot sign again.

Revoking an agent programmatically

Revocation requires cryptographic proof to prevent malicious internal tampering:

Request a revocation challenge:

curl -X POST https://staging.api.sohopay.xyz/api/v1/agents/agt_3f9a1c8e/revocations/challenge \
  -H "Authorization: Bearer $SOHOPAY_API_KEY"

Submit signed revocation:

curl -X POST https://staging.api.sohopay.xyz/api/v1/agents/agt_3f9a1c8e/revoke \
  -H "Authorization: Bearer $SOHOPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "challenge_id": "rev_chal_98765",
    "signature": "0x_signed_revocation_challenge"
  }'

You can also permanently revoke an agent with a single confirmation prompt in the Borrower Portal.

Disaster recovery & cold storage

If an active signing share is corrupted, SohoPay initiates a disaster recovery ceremony using the escrowed Cold Backup Share:

SohoPay’s monitoring detects quorum interruption and automatically pauses the agent to safeguard funds.
The cold share is brought online under multi-party custody controls.
Fresh shares are generated and re-established (forced rotation).
The system delivers an agent.key_rotated webhook event and unpauses the agent.

SohoPay staff will never ask you for private keys, seed phrases, or sensitive passwords. Always report suspicious requests to security@sohopay.xyz.

Operational best practices

Enforce velocity controls: Set tight daily_limit thresholds on every agent. Even during an incident, total exposure is bounded by daily limits.
Monitor rotation events: Set up automated alerts for unexpected agent.key_rotated webhook deliveries.
Drain before rotation: Pause the agent briefly before scheduled maintenance rotations to ensure zero in-flight authorization conflicts.

Next steps

MPC Signing Protocol

Read the cryptographic specifications of our threshold signatures.

Webhooks Guide

Handle real-time agent.key_rotated and payment lifecycle events.

Vault & Funding

Manage your USDC collateral backing and revolving capacity.

Getting Started

Merchant Integration

Agent Wallet Setup

Payment Flow

Protocol & Standards

Compliance & Risk

Operational Dashboards

The 2-of-3 MPC architecture

Key security properties

How to rotate agent keys

Method A: Via the Borrower Portal (Recommended)

Method B: Programmatic rotation via Gateway API

Step 1: Initiate key rotation (PoP)

Step 2: Check rotation status & fetch challenge

Step 3: Reauthorize with operator wallet signature

Webhook notification: `agent.key_rotated`

Emergency agent revocation (Kill Switch)

Revoking an agent programmatically

Disaster recovery & cold storage

Operational best practices

Next steps

MPC Signing Protocol

Webhooks Guide

Vault & Funding

​The 2-of-3 MPC architecture

​Key security properties

​How to rotate agent keys

​Method A: Via the Borrower Portal (Recommended)

​Method B: Programmatic rotation via Gateway API

​Step 1: Initiate key rotation (PoP)

​Step 2: Check rotation status & fetch challenge

​Step 3: Reauthorize with operator wallet signature

​Webhook notification: agent.key_rotated

​Emergency agent revocation (Kill Switch)

​Revoking an agent programmatically

​Disaster recovery & cold storage

​Operational best practices

​Next steps

MPC Signing Protocol

Webhooks Guide

Vault & Funding

The 2-of-3 MPC architecture

Key security properties

How to rotate agent keys

Method A: Via the Borrower Portal (Recommended)

Method B: Programmatic rotation via Gateway API

Step 1: Initiate key rotation (PoP)

Step 2: Check rotation status & fetch challenge

Step 3: Reauthorize with operator wallet signature

Webhook notification: `agent.key_rotated`

Emergency agent revocation (Kill Switch)

Revoking an agent programmatically

Disaster recovery & cold storage

Operational best practices

Next steps