> ## Documentation Index
> Fetch the complete documentation index at: /llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Agents use OAuth into hosted MCP. Merchants use a JWT or an sk_live_ API key.

SohoPay has two caller types, and they do not share a key format. Agents never see the merchant API key. Merchants never receive the agent's workload key.

## Agents

The host connects to `https://staging.mcp.sohopay.ai/mcp` with OAuth 2.1. Dynamic client registration is enabled on staging for Cursor, Claude, and loopback redirects. After the borrower grants access, the host calls MCP tools with a borrower token.

Production (after cutover): `https://mcp.sohopay.ai/mcp`. Integrate on staging until SohoPay enables production settlement.

The token is a JWT whose scopes are limited by how far onboarding has progressed. Request the scopes the next tool needs. `prepare_x402_payment` requires all three of `spend:intent:create`, `policy:evaluate`, and `signing:request`. Onboarding also needs `borrower:token`, `credit:facility:accept`, `agent:key:register` when rotating a key, `handle:claim`, and `repayment:execute` when repaying.

Refresh the borrower token when it is within about three minutes of expiry. A scope list on an identity call is not a refresh signal.

> [!WARNING]
>
> Do not put a borrower seed or private key in the agent, the MCP config, or a skill. Wallet proof, the agent grant, and repayment are EIP-712 signatures the borrower makes in their own wallet. See [Key management](/guides/key-management.md).

## Merchants

Send `Authorization: Bearer <credential>` on facilitator routes.

* A merchant user JWT from the SohoPay app, or
* An API key shaped `sk_live_` plus a base64url secret, bound to one merchant UUID.

There is no `sk_test_` prefix. Staging keys use `sk_live_` too. Keys are issued when SohoPay provisions the merchant. They are not minted from a public dashboard signup.

Capture requires the permission `x402:settle:create`. Verify and status polls require `x402:settle:read`. Machine callers using an API key satisfy the capture step-up on that route only.

```bash
curl https://staging.api.sohopay.ai/api/v1/facilitator/supported \
  -H "Authorization: Bearer $SOHO_API_KEY"
```

`GET /api/v1/facilitator/supported` and `GET /api/v1/facilitator/health` are the public discovery and liveness routes.

## Idempotency

Send `Idempotency-Key: <uuid v4>` on mutating calls, including capture and MCP writes. The same key with the same body replays the first result. The same key with a different body is a conflict. A 402 payment keeps one idempotency key for its `orderRef` across retries.

## Identifiers

Borrowers, merchants, and operational agents are UUIDs. On-chain ids are `bytes32` values derived from those UUIDs. Store `operational_agent_id` from `register_borrower` and pass it when the borrower has more than one terminal.

## Next steps

> [card] [Borrower onboarding](/guides/borrower-onboarding.md)
>
> The stops that need the borrower in person.

> [card] [Merchant integration](/guides/merchant-integration.md)
>
> Where the API key is used.
