Autenticación

La autenticación es la forma en que Mono confirma que una solicitud viene de tu sistema y no de alguien más. Cada producto de Mono requiere autenticación en cada solicitud — no hay acceso anónimo. Esta página cubre las convenciones que aplican a todos los productos. El tipo exacto de credencial (API key vs. token OAuth) depende de qué producto estés integrando.

Antes de empezar

Vas a necesitar:

• Una cuenta de Mono activa con credenciales para el entorno al que quieres llamar (sandbox o producción).
• Soporte HTTPS en tu cliente. Mono rechaza solicitudes que no usen TLS.
• Un lugar seguro para almacenar credenciales — un gestor de secretos, variables de entorno en un runtime gestionado, o equivalente. Nunca las commitees al control de versiones.

Cómo viajan las credenciales

Todas las solicitudes autenticadas llevan la credencial en el header Authorization usando el esquema Bearer.

Authorization: Bearer <your_credential>

Esto aplica sin importar si la credencial es una API key estática o un token OAuth de corta duración. El nombre del header y el esquema son fijos; solo cambia el valor entre productos.

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

Entornos

Mono separa las credenciales de producción de las de sandbox. No son intercambiables:

• Las llaves de sandbox solo funcionan contra las URLs base de sandbox y nunca mueven dinero real.
• Las llaves de producción mueven dinero real. Trátalas con el mismo cuidado que una contraseña bancaria.

Cada página de producto describe la URL base exacta para sus entornos de sandbox y producción.

Fallas

Cuando la autenticación falla, Mono devuelve uno de dos códigos de estado HTTP:

Ambas respuestas siguen el envelope de error estándar. No reintentes un 401 o 403 sin antes refrescar o reemplazar la credencial — los reintentos con la misma credencial mala seguirán fallando y pueden disparar penalizaciones por límite de tasa.

Rotación de credenciales

Rota las credenciales en un cronograma y de inmediato tras cualquier sospecha de exposición (un log filtrado, un ex-empleado, un laptop comprometido). El procedimiento de rotación depende del producto:

• API keys (Banking, Core): genera una nueva llave en el Dashboard de Mono, despliégala, y luego revoca la antigua. Las llaves no expiran automáticamente; la rotación es tu responsabilidad.
• Tokens OAuth (Bre-B Participant, Wallet): los tokens expiran solos. La rotación en sentido operativo significa rotar el client secret o la contraseña subyacentes que se usan para obtener nuevos tokens.

Particularidades por producto

Las reglas entre productos de arriba son universales. El tipo exacto de credencial, cómo obtenerla y cualquier scope específico del producto se documentan en la página de autenticación de cada producto:

Siguientes pasos

• Claves de idempotencia — cómo reintentar operaciones de escritura de forma segura.
• Errores y reintentos — el envelope de error estándar devuelto en fallas de auth, más la política de reintentos.
• Formatos de datos — convenciones para fechas, dinero y números de teléfono.