Autenticación

Cada solicitud a la API de Banking debe demostrar que viene de tu empresa. Puedes demostrarlo con una API key de larga duración, o con un access token de corta duración que tu servidor pide por su cuenta. Mono acepta ambos en todos los endpoints de Banking, así que puedes elegir el que mejor encaje con tus prácticas de seguridad.

Antes de empezar

Vas a necesitar:

• Acceso al Mono Dashboard de tu organización.
• Un cliente HTTPS. Mono rechaza las solicitudes que no usan TLS.
• Un lugar seguro para los secretos, como un gestor de secretos. Nunca subas credenciales al control de versiones.

Las convenciones que comparten todos los productos de Mono, como el formato del header y los entornos, están en Estándares de autenticación.

Elige una credencial

Un rol es un conjunto de permisos con nombre, como "Admin" o "Viewer", asignado a una API key. Un scope es un permiso individual, como transfers:readonly, asignado a un access token. Mono relaciona cada permiso de rol con los scopes que autorizan la misma acción, así que un endpoint acepta cualquiera de las dos credenciales para la misma operación.

Opción 1: API keys

Una API key es una cadena secreta que sigue siendo válida hasta que la revoques. Para crear o revocar llaves, inicia sesión en el Mono Dashboard y abre la sección de gestión de API keys.

Al crear una llave, elige sus roles. La llave puede hacer exactamente lo que esos roles permiten. Por ejemplo, una llave con el rol "Viewer" puede leer datos, pero no mover dinero.

Envía la llave en el header Authorization de cada solicitud:

curl https://api.cuentamono.com/v1/accounts \
  -H "Authorization: Bearer $MONO_API_KEY"

Las llaves no expiran, así que rotarlas es tu responsabilidad: crea una llave nueva, despliégala y luego revoca la anterior.

Opción 2: access tokens de OAuth 2.0

OAuth 2.0 es un estándar de la industria para emitir credenciales temporales. Mono usa su flujo de client credentials, pensado para integraciones de servidor a servidor. Tu servidor cambia un client ID y un client secret permanentes por un access token que dura 30 minutos. Piénsalo como cambiar el carné de empleado por un pase de un día: el pase vence y el carné se queda guardado en la caja fuerte.

Obtén una credencial

Las credenciales OAuth de Banking todavía no son de autoservicio: el Mono Dashboard no puede crearlas para organizaciones de Banking. Para obtener una, contacta a tu equipo de cuenta en Mono e indícale qué scopes necesita tu integración.

Mono te entrega un client ID y un client secret. Guarda ambos en tu gestor de secretos apenas los recibas. Para cambiar los scopes después, o para desactivar o eliminar la credencial, contacta al mismo equipo.

Pide un access token

Llama al endpoint de token con grant_type=client_credentials, tu client ID y tu secret, y los scopes que necesitas, separados por espacios:

curl https://api.cuentamono.com/v1/oauth/token \
  -d grant_type=client_credentials \
  -d client_id="$MONO_CLIENT_ID" \
  -d client_secret="$MONO_CLIENT_SECRET" \
  -d scope="accounts:readonly transfers"

El endpoint acepta application/x-www-form-urlencoded, como arriba, o los mismos campos en JSON. En sandbox, usa https://api.sandbox.cuentamono.com.

{
  "access_token": "<access_token>",
  "token_type": "Bearer",
  "expires_in": 1800,
  "refresh_token": "<refresh_token>",
  "scope": "accounts:readonly transfers"
}

Llama a la API

Envía el access token en el header Authorization, igual que una API key:

curl https://api.cuentamono.com/v1/accounts \
  -H "Authorization: Bearer $MONO_ACCESS_TOKEN"

Renueva el token

expires_in es la vida restante del token en segundos: 1800 cuando se emite. Pide un token nuevo antes de que se acabe. Tienes dos formas:

• Pide un token nuevo con tus client credentials, igual que arriba. Es la opción más simple para un servidor que siempre tiene su secret.
• Usa el refresh token. La respuesta también trae un refresh_token, válido por un día. Cámbialo por un access token nuevo:

curl https://api.cuentamono.com/v1/oauth/token \
  -d grant_type=refresh_token \
  -d client_id="$MONO_CLIENT_ID" \
  -d client_secret="$MONO_CLIENT_SECRET" \
  -d refresh_token="$MONO_REFRESH_TOKEN"

Cada refresh devuelve un refresh token nuevo. Usa el nuevo la próxima vez y descarta el anterior.

Consulta o revoca un token

Otros dos endpoints reciben tu client ID y tu secret, más el token:

• Introspect (grant_type=introspect) te dice si un token sigue activo, cuándo expira y qué scopes trae. Un token expirado o desconocido devuelve {"active": false}.
• Revoke (grant_type=revoke) invalida de inmediato un access token o un refresh token. Responde 200 aunque el token ya hubiera expirado.

Revoca los tokens que ya no necesites, por ejemplo cuando retires un servidor. Los contratos de los endpoints están en la referencia de autenticación de Banking.

Scopes

Pide los scopes más acotados que necesite tu integración. Dos reglas aplican a todo el catálogo:

• Un scope sin sufijo, como transfers, autoriza todas las acciones sobre ese recurso, incluidas las acciones específicas que aparecen debajo.
• Un scope :readonly autoriza solo lecturas. No incluye las acciones específicas: cards:readonly no autoriza cards:details.

Fallas

Los endpoints de token, introspect y revoke responden los errores en formato OAuth, con los campos error y error_description. Por ejemplo, 400 invalid_scope significa que pediste un scope que tu credencial no tiene.

Todos los demás endpoints responden con el envelope de error estándar:

Siguientes pasos

• Referencia de autenticación — los endpoints de token, introspect y revoke en detalle.
• Estándares de autenticación — header, entornos y reglas de rotación que comparten todos los productos.
• Errores y reintentos — el envelope de error y cuándo reintentar.