Every SohoPay API request authenticates with a secret API key sent as a Bearer token. This page covers the key lifecycle end to end — generating keys, using them, rotating them — plus how webhook signatures and rate-limit headers work.

​
API key format

Keys are environment-scoped secrets with a prefix that tells you where they work: A key only works against its own environment — a sk_test_ key against the mainnet URL returns 401 INVALID_API_KEY.

​
Generating a key

  1. Sign in to the SohoPay Dashboard.
  2. Go to Settings → API Keys → Create key.
  3. Name the key after the service that will use it (e.g. checkout-backend-prod).
  4. Copy the key immediately — the full value is shown once and never again. Only the prefix and last four characters remain visible in the dashboard.
Create one key per deployed service. When a service is decommissioned or a key leaks, you revoke exactly one credential without breaking anything else.

​
Bearer authentication

Send the key in the Authorization header on every request:
Requests with a missing, malformed, or revoked key return 401 with the standard error envelope:
Never embed API keys in client-side code — browser bundles, mobile apps, agent prompts, or anything else that ships to users. Keys grant full account access, and anything client-side can be extracted in minutes. All SohoPay calls must go through your backend, with keys loaded from environment variables or a secrets manager (see Environment Setup).

​
Webhook signing

Inbound authentication is only half the picture — SohoPay also signs everything it sends to you. Every webhook delivery carries an HMAC-SHA256 signature in the Sohopay-Signature header and the send time in Sohopay-Timestamp. Verify the signature before trusting any payload; reject anything unsigned or stale. The signature is computed over ${timestamp}.${raw_body} using your endpoint’s signing secret. Full verification code in TypeScript and Python lives in Webhook Events, and endpoint setup is covered in the webhooks guide.

​
Rate-limit headers

Every response includes your current rate-limit state: When you exceed the limit, the API returns 429 RATE_LIMITED. Respect Retry-After rather than retrying immediately; hammering a 429 only extends the wait. Per-agent transaction limits are separate and enforced by the Policy Service — see Rate Limits for both layers.

​
Key rotation

Rotate keys on a schedule (quarterly is a reasonable default), when a team member with key access leaves, or immediately on any suspected exposure. Multiple active keys can coexist, so rotation is zero-downtime:
1

Create the new key

In the dashboard, create a replacement key (Settings → API Keys → Create key). The old key keeps working — both are valid simultaneously.
2

Deploy the new key

Update the secret in your secrets manager or environment config and roll your services. Verify traffic succeeds with the new key by checking any authenticated call returns 200.
3

Revoke the old key

Back in the dashboard, revoke the old key. Requests using it fail from that moment with 401 INVALID_API_KEY — so confirm no service still holds it before revoking.
If a key was exposed publicly (committed to git, pasted in a shared doc), skip the graceful order: revoke it first, then deploy a new one. A brief outage beats an open credential.
Agent signing keys are a separate concern from API keys — rotating an agent’s MPC key share is covered in Key Management, and emits an agent.key_rotated webhook.

​
Next steps

Webhooks Guide

Register endpoints and verify HMAC-SHA256 signatures.

API Introduction

Base URLs, idempotency, pagination, and versioning.

Key Management

Agent signing keys and the 2-of-3 MPC model.