> ## 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.

# Autenticación

> Payzor usa tres tipos de credencial. Cada una abre una porción distinta de la API, y nada más.

# Autenticación

Payzor tiene tres tipos de actor, y cada uno se autentica distinto:

| Actor                  | Credencial   | Cabecera                           | Qué puede hacer                                                              |
| ---------------------- | ------------ | ---------------------------------- | ---------------------------------------------------------------------------- |
| **Negocio (comercio)** | `sk_mch_...` | `Authorization: Bearer sk_mch_...` | Crear cargos, PayLinks y cobrar contra presupuestos                          |
| **Agente**             | `pz_sk_...`  | `Authorization: Bearer pz_sk_...`  | Pagar cargos, aceptar PayLinks, pagar y transferir desde su propia billetera |
| **Usuario de consola** | Sesión JWT   | `Authorization: Bearer <jwt>`      | Registrar comercios, gestionar webhooks, aprobar pagos, exportar             |

Todas las credenciales viajan en la misma cabecera; el prefijo le dice a Payzor quién eres.

```bash theme={null}
# Una llamada de comercio
curl https://tu-host-payzor/merchant/me \
  -H "Authorization: Bearer sk_mch_..."

# Una llamada de agente
curl https://tu-host-payzor/balance \
  -H "Authorization: Bearer pz_sk_..."

# Una llamada de consola
curl https://tu-host-payzor/settings/webhooks \
  -H "Authorization: Bearer <jwt>"
```

## Keys de comercio (`sk_mch_...`)

Se emiten cuando un usuario de consola registra un negocio con `POST /merchants`. Propiedades:

* Se muestran **una sola vez** al crearlas; solo se guarda un hash.
* Están limitadas a exactamente un registro de comercio: nunca pueden tocar el dinero de otro.
* Para rotarlas, crea un comercio nuevo y migra (la API de revocación está en la hoja de ruta).

## Keys de agente (`pz_sk_...`)

Se emiten por agente desde la consola o la CLI. Propiedades:

* La key *es* la identidad del agente para mover dinero; cada pago se evalúa contra la política de ese agente.
* Un agente solo puede gastar su propio saldo. No hay forma de pasar un `agentId` arbitrario; si el modelo pudiera elegir la billetera, la key no limitaría nada.

## Sesiones de consola (JWT)

Se obtienen entrando por la consola (correo o Google OAuth). Son necesarias para:

* `POST /merchants`
* `GET|POST /settings/webhooks` y sus entregas
* `POST /approvals/:id/grant|reject` (aprobaciones humanas)
* `POST /kyt/screen`
* `GET /export/transactions.csv`

## Errores

Una credencial ausente o inválida devuelve `401` con un cuerpo JSON que explica qué credencial se esperaba:

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

Una credencial válida actuando donde no le corresponde devuelve `403`.

<Note>
  Algunos despliegues permiten acceso anónimo en modo de desarrollo local (`PAYZOR_REQUIRE_API_KEY=false`). Nunca dependas de esto fuera de pruebas locales; en producción se exigen keys en todas partes.
</Note>