Authentication

Authentication is how Mono confirms that a request is coming from your system and not from someone else. Every Mono product requires authentication on every request — there is no anonymous access. This page covers the conventions that apply across products. The exact credential type (API key vs. OAuth token) depends on which product you are integrating.

Before you start

You will need:

• An active Mono account with credentials for the environment you want to call (sandbox or production).
• HTTPS support in your client. Mono refuses non-TLS requests.
• A safe place to store credentials — a secrets manager, environment variables in a managed runtime, or an equivalent. Never commit them to source control.

How credentials travel

All authenticated requests carry the credential in the Authorization header using the Bearer scheme.

Authorization: Bearer <your_credential>

This is true regardless of whether the credential is a static API key or a short-lived OAuth access token. The header name and scheme are fixed; only the value changes between products.

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

Environments

Mono separates production credentials from sandbox credentials. They are not interchangeable:

• Sandbox keys only work against sandbox base URLs and never move real money.
• Production keys move real money. Treat them with the same care as a banking password.

Each product page describes the exact base URL for its sandbox and production environments.

Failures

When authentication fails, Mono returns one of two HTTP status codes:

Both responses follow the standard error envelope. Do not retry a 401 or 403 without first refreshing or replacing the credential — retries with the same bad credential will keep failing and may trigger rate-limit penalties.

Rotating credentials

Rotate credentials on a schedule and immediately after any suspected exposure (a leaked log, an ex-employee, a compromised laptop). The rotation procedure depends on the product:

• API keys (Banking, Core): generate a new key in the Mono Dashboard, deploy it, then revoke the old one. Keys do not expire automatically; rotation is your responsibility.
• OAuth tokens (Bre-B Participant, Wallet): tokens expire on their own. Rotation in the operational sense means rotating the underlying client secret or password used to obtain new tokens.

Per-product specifics

The cross-product rules above are universal. The exact credential type, how to obtain one, and any product-specific scopes are documented on each product's authentication page:

Next steps

• Idempotency Keys — how to safely retry write operations.
• Errors and retries — the standard error envelope returned on auth failures, plus retry policy.
• Data Formats — date, money, and phone number conventions.