Autenticación

Cada solicitud a la API de Core 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 Core, así que puedes elegir el que mejor encaje con tus prácticas de seguridad.

Antes de empezar

Vas a necesitar:

• Una organización de Mono con Core habilitado, y acceso a su Mono Dashboard.
• 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 payouts: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.

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

curl https://api.cuentamono.com/v1/ledger/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.

Crea una credencial

En el Mono Dashboard, abre la sección Credentials de tu organización y crea una credencial:

1. Elige los scopes que la credencial puede pedir. Puedes cambiarlos después.
2. Copia el client ID y el client secret. El dashboard muestra el secret una sola vez.
3. Guarda ambos en tu gestor de secretos.

No eliges entre Core y Banking: una organización de Core siempre recibe credenciales de Core. Desde la misma sección también puedes desactivar, activar o eliminar una credencial.

Pide un access token

Llama al endpoint de token de Core 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/core/oauth/token \
  -d grant_type=client_credentials \
  -d client_id="$MONO_CLIENT_ID" \
  -d client_secret="$MONO_CLIENT_SECRET" \
  -d scope="ledger:readonly payouts"

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": "ledger:readonly payouts"
}

Llama a la API

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

curl https://api.cuentamono.com/v1/ledger/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/core/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 Core.

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 cards, 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.

Bre-B es el sistema de pagos inmediatos de Colombia, operado por el Banco de la República. La resolución de destinos convierte una llave Bre-B, como un número de celular, en la cuenta a la que apunta.

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.
• Arquitectura — cómo fluye una solicitud después de la autenticación.
• Buenas prácticas — rotación de llaves, scopes mínimos y almacenamiento de credenciales.