# auth.md

You are an agent that wants to call the NoHoldPay merchant API on a merchant's
behalf. NoHoldPay is a non-custodial crypto payment gateway: payments settle
directly to wallets the merchant controls. This file describes how credentials
are issued today and how to handle them safely.

Three hosts are relevant, all operated by NoHoldPay:

- Resource server: https://api.noholdpay.com (the merchant API you will call; OpenAPI spec at https://noholdpay.com/openapi.json).
- Dashboard: https://app.noholdpay.com (where the merchant manages the account and API keys).
- MCP server: https://mcp.noholdpay.com (the same API over the Model Context Protocol; see below).

## Current state

NoHoldPay does not support agentic registration today. There is no OAuth
authorization server, no `/.well-known/oauth-protected-resource` or
`/.well-known/oauth-authorization-server` metadata, no OpenID Connect issuer,
and no programmatic signup endpoint. Accounts are created by a human in the
dashboard (email and password, or Google or GitHub sign-in), and API keys are
created by that signed-in human. Credentials are issued out of band; this file
tells you how to pick one up and use it without putting it at risk.

## Supported credential: API key, supplied out of band

The only credential is an API key, sent as a bearer token. Keys carry a mode
prefix:

- `pk_test_...`: test mode. Payments use testnet chains and no real money.
  Prefer this while building or verifying an integration.
- `pk_live_...`: live mode. Payments are real.

The merchant issues keys at https://app.noholdpay.com/api-keys. The full key is shown exactly
once at creation and only a hash is stored, so a lost key means creating a new
one. The merchant supplies the key to you through a secure channel, never by
pasting it into a conversation.

### How to pick the key up

Look for it in this order and stop at the first that exists:

1. `NOHOLDPAY_API_KEY` in your process environment.
2. A project `.env` file the merchant has told you to read.

If neither is set, do not ask the merchant to paste the key into the
conversation. Ask them to create one in the dashboard (start with `pk_test_`),
put it in `NOHOLDPAY_API_KEY`, and resume the task.

### How to use the key

Send it on every request as a bearer token:

```http
POST /api/v1/payments HTTP/1.1
Host: api.noholdpay.com
Authorization: Bearer $NOHOLDPAY_API_KEY
Content-Type: application/json
```

## MCP server

The same operations are available over the Model Context Protocol at https://mcp.noholdpay.com/mcp
(streamable HTTP, stateless). Authenticate with the same API key in the same
`Authorization: Bearer` header described above; the key never leaves the request.
The machine-readable server card is at https://mcp.noholdpay.com/mcp/server-card (media type
`application/mcp-server-card+json`), and an origin catalog pointing to it is at
https://noholdpay.com/.well-known/mcp/catalog.json. Use `pk_test_` keys here while
building; the server rejects live keys unless the operator has enabled them.

Never echo the key, log it, commit it, or send it to any host other than the
NoHoldPay resource server or MCP server named above.

## Errors

Errors return `{ "error": { "code": "...", "message": "..." } }`. Branch on the
stable `code`, never on the message text.

| HTTP | code | What to do |
| ---- | ---- | ---------- |
| 401 | `UNAUTHORIZED` | The key is missing, malformed, revoked, or wrong. Re-read it from the environment; if it still fails, ask the merchant for a fresh key. |
| 429 | `RATE_LIMITED` | Per-key rate limit hit. Back off and retry later; do not rotate keys to evade it. |

## Revocation

The merchant can revoke or deactivate any key from the dashboard at any time.
There is no agent-facing revocation endpoint; if a key stops working with
`UNAUTHORIZED`, treat it as revoked and ask the merchant for a new one.

## What you can do with a key

Machine-readable skills for common tasks are indexed at https://noholdpay.com/.well-known/agent-skills/index.json
(create a payment, a payment link, or an invoice). The full API surface is in
the OpenAPI spec at https://noholdpay.com/openapi.json, the RFC 9727 catalog at
https://noholdpay.com/.well-known/api-catalog, and the human docs at https://docs.noholdpay.com.