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

# Authentication

> Payzor uses three credential types. Each one unlocks a different slice of the API, and nothing more.

# Authentication

Payzor has three kinds of actors, and each authenticates differently:

| Actor                   | Credential   | Header                             | Can do                                                         |
| ----------------------- | ------------ | ---------------------------------- | -------------------------------------------------------------- |
| **Business (merchant)** | `sk_mch_...` | `Authorization: Bearer sk_mch_...` | Create charges, PayLinks, charge against budgets               |
| **Agent**               | `pz_sk_...`  | `Authorization: Bearer pz_sk_...`  | Pay charges, accept PayLinks, pay/transfer from its own wallet |
| **Console user**        | JWT session  | `Authorization: Bearer <jwt>`      | Register merchants, manage webhooks, approve payments, exports |

All credentials travel in the same header; the prefix tells Payzor who you are.

```bash theme={null}
# A merchant call
curl https://your-payzor-host/merchant/me \
  -H "Authorization: Bearer sk_mch_..."

# An agent call
curl https://your-payzor-host/balance \
  -H "Authorization: Bearer pz_sk_..."

# A console call
curl https://your-payzor-host/settings/webhooks \
  -H "Authorization: Bearer <jwt>"
```

## Merchant keys (`sk_mch_...`)

Issued when a console user registers a business with `POST /merchants`. Properties:

* Shown **once** at creation; only a hash is stored.
* Scoped to exactly one merchant record: it can never touch another merchant's money.
* Rotate by creating a new merchant and migrating (revocation API is on the roadmap).

## Agent keys (`pz_sk_...`)

Issued per agent from the console or CLI. Properties:

* The key *is* the agent's identity for money movement; every payment is evaluated against that agent's policy.
* An agent can only spend its own balance. There is no way to pass an arbitrary `agentId`; if the model could choose the wallet, the key would constrain nothing.

## Console sessions (JWT)

Obtained by logging in through the console (email or Google OAuth). Required for:

* `POST /merchants`
* `GET|POST /settings/webhooks`, deliveries
* `POST /approvals/:id/grant|reject` (human approvals)
* `POST /kyt/screen`
* `GET /export/transactions.csv`

## Errors

Missing or invalid credentials return `401` with a JSON body explaining which credential was expected:

```json theme={null}
{ "error": "API key de merchant inválida (sk_mch_...)" }
```

A valid credential acting where it doesn't belong returns `403`.

<Note>
  Some deployments allow anonymous access in local dev mode (`PAYZOR_REQUIRE_API_KEY=false`). Never rely on this outside local testing; production requires keys everywhere.
</Note>