---
title: "Autenticación"
description: "Elegir y usar JWT de management o API keys de negocio con ambientes y scopes aislados."
---

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

# Autenticación

# 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í:

```http
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.

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

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

El ciclo completo está en [Usuarios y sesión](/resources/users).

## API keys

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

```text
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

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

Consultá [Métodos de pago de la cuenta](/resources/account-payment-methods) 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

```json
{
  "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.

Source: https://docs.pagofast.com/authentication/index.mdx