Autenticación

La API usa OAuth 2.0 con flujo client_credentials y tokens JWT de larga duración (12 horas).

Obtener un token

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

{
  "clientId": "your-client-id",
  "clientSecret": "your-client-secret"
}

Respuesta

{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR...",
  "tokenType": "Bearer",
  "expiresIn": 43200,
  "scope": "clients:read clients:write receivables:read receivables:write ..."
}

Campo	Descripción
accessToken	JWT a usar en Authorization: Bearer ...
tokenType	Siempre Bearer
expiresIn	Segundos hasta expiración. Default 43200 (12 horas)
scope	Lista de scopes habilitados separados por espacio

Usar el token

Incluí el accessToken como bearer token en cada request:

GET /v1/me
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR...

Renovación

Cuando el token expira, hacé un nuevo POST /v1/auth/login para obtener otro. No hay refresh tokens.

Para integraciones server-to-server: cacheá el token en memoria, renovalo antes de que expire (típicamente 5 minutos antes), y reusalo entre requests. El campo expiresIn del response indica el tiempo de vida en segundos.

Scopes

Cada API key tiene un set de scopes que limita lo que puede hacer. El token devuelve los scopes activos en el campo scope.

Scope	Permite
clients:read	Leer clientes
clients:write	Crear y actualizar clientes
associates:read	Leer asociados
associates:write	Crear, actualizar y deshabilitar asociados
receivable-accounts:read	Leer cuentas recaudadoras
receivable-accounts:write	Crear, actualizar, deshabilitar cuentas recaudadoras
current-accounts:read	Leer cuentas corrientes (MAIN/SUB)
receivables:read	Leer comprobantes
receivables:write	Crear, actualizar, cambiar estado de comprobantes
movements:read	Leer movimientos
settlements:read	Leer liquidaciones
route-settlements:read	Leer rendiciones por hoja de ruta
route-settlements:write	Crear/actualizar rendiciones
reports:read	Generar y descargar reportes
webhooks:admin	Gestionar webhooks

Cuando un request requiere un scope que el token no tiene, la respuesta es 403 insufficient-scope.

Errores comunes

Escenario	HTTP	code
Credenciales incorrectas	401	invalid-credentials
Token expirado	401	token-expired
Token mal formado	401	invalid-token
Falta scope necesario	403	insufficient-scope
Rate limit en /auth/login	429	rate-limit-exceeded

GET /v1/me

Recurso de conveniencia para inspeccionar el contexto del token activo. Útil al integrar para confirmar credenciales, customer y ambiente:

GET /v1/me
Authorization: Bearer eyJ...

200 OK
{
  "customer": {
    "id": 17,
    "businessName": "DistribuidoraDemo S.A.",
    "taxId": "30999999999",
    "creationDate": "2025-11-01T10:00:00-03:00"
  },
  "apiKey": {
    "id": 88,
    "name": "ERP Producción",
    "scopes": [
      "clients:read", "clients:write",
      "associates:read", "associates:write",
      "receivable-accounts:read", "receivable-accounts:write",
      "receivables:read", "receivables:write",
      "movements:read", "settlements:read", "reports:read",
      "webhooks:admin"
    ],
    "environment": "PRODUCTION",
    "rateLimitTier": "STANDARD"
  }
}

Rotación de credenciales

El clientSecret se puede rotar contactando al equipo de Max Pay. En una próxima versión se expondrá un endpoint self-service.