Elegir y usar JWT de management o API keys de negocio con ambientes y scopes aislados.

Autenticación

PagoFast usa tokens Bearer, pero tiene dos mecanismos con propósitos distintos:

Mecanismo	Para qué se usa	Ejemplos de rutas
JWT de usuario	Management (`/v1/users`, `/v1/account/*`) y también rutas de negocio cuando el OpenAPI lo admite.	`/v1/auth/`, `/v1/users`, `/v1/account/`, `/v1/payments`.
API key	Camino típico de integración de negocio: métodos habilitados y pagos en nombre de una cuenta.	`/v1/payment-methods`, `/v1/payments`.

Ambos se envían así:

Authorization: Bearer <token>

No se usan cookies de sesión. Las API keys deben vivir exclusivamente en servicios backend; nunca en navegador, aplicación móvil distribuida ni código fuente.

JWT de usuario

El login entrega un access token de corta duración y un refresh token rotativo. Usá el access token para management y renovalo con el refresh token. La reutilización de un refresh ya rotado puede revocar la cadena de sesión.

POST /v1/auth/login
Content-Type: application/json

{
  "email": "ops@comercio.com",
  "password": "una-clave-segura"
}

El ciclo completo está en Usuarios y sesión.

API keys

Las keys se crean mediante management y su secreto completo se muestra una sola vez.

sk_test_...  → ambiente de prueba
sk_live_...  → ambiente productivo

Una key determina automáticamente owner, ambiente, scopes y métodos habilitados. No envíes user_id, tenant_id ni api_key_id en requests de pagos para intentar cambiar ese contexto.

Scopes

Scope	Permite
`payment_methods:read`	Listar y obtener métodos habilitados.
`payments:create`	Crear pagos.
`payments:read`	Consultar pagos.
`payments:cancel`	Cancelar pagos cuando el método lo soporte.
`refunds:create`	Crear reembolsos cuando el método lo soporte.

La autorización efectiva requiere a la vez el scope, el método habilitado y la capability correspondiente. Tener refunds:create, por ejemplo, no agrega capability refunds a un método.

Recorrido mínimo

Iniciar sesión y obtener un JWT.
Crear una API key test con los scopes mínimos.
Configurar o elegir un Payment Method test.
Habilitar ese método para la key.
Llamar a negocio con Authorization: Bearer sk_test_....

Consultá Métodos de pago de la cuenta para configurar y habilitar métodos.

Rotación y almacenamiento

Guardá secretos en un gestor de secretos o variables protegidas del runtime.
Mostrá y copiá la API key solo durante su creación.
Creá una nueva key, migrá el tráfico y recién después revocá la anterior.
Usá keys distintas por aplicación, ambiente y nivel de privilegio.
Otorgá únicamente los scopes necesarios.
No registres tokens ni los incluyas en URLs.

Errores

{
  "error": {
    "code": "invalid_api_key",
    "message": "La API key es inválida, expiró o fue revocada.",
    "category": "authentication",
    "retryable": false,
    "request_id": "req_019f704f89d77e83",
    "details": {}
  }
}

Código	Interpretación	Acción
`invalid_api_key`	Key inexistente, expirada o revocada.	No reintentar; reemplazar la credencial.
`unauthorized`	Falta JWT o no es válido.	Renovar sesión o autenticarse.
`insufficient_scope`	La key no tiene el scope requerido.	Crear/usar una key con el scope; no repetir sin cambios.
`insufficient_role`	El usuario no tiene rol suficiente.	Solicitar que un admin realice la operación.

Una key del ambiente equivocado no debe reemplazarse cambiando su prefijo: creá o solicitá una credencial del ambiente correcto.