Authentication - Monaco Docs

Overview

Monaco’s public API is hosted on api.monaco.com The Monaco Public API uses API key authentication. Every request must include a valid API key in the Authorization header as a bearer token.

Obtaining an API Key

API keys are created through the Monaco application (Settings > API Keys). When you create a key you will receive a plaintext key with the prefix mks_ — this is the only time the plaintext value is shown. Monaco stores a hash of the key value; the original value cannot be retrieved later.

mks_<48-char-url-safe-token>

Each API key is scoped to an organization and optionally tied to a specific user. If no user is set, the key operates as the user who created it.

Authenticating Requests

Include the key in the Authorization header on every request as a bearer token:

curl -X POST https://api.monaco.com/v1/contacts/list \
  -H "Authorization: Bearer mks_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"page": 1, "page_size": 10}'

Header Reference

Header	Required	Description
`Authorization`	Yes	Your API key as a bearer token
`Content-Type`	Yes (POST)	Must be `application/json` for request bodies

Error Responses

Status	Meaning
`401`	Missing or invalid API key
`403`	API key is valid but lacks required access
`429`	Rate limit exceeded

401 — No Key / Invalid Key

Returned when the Authorization header is missing or the key does not match any active key.

{
  "detail": "No key found"
}

429 — Rate Limited

All endpoints enforce per-org rate limiting. Every org has a limit of 100 requests per minute. When you exceed the limit, the response includes headers to help you back off:

Response Header	Description
`X-RateLimit-Limit`	Maximum requests allowed per window
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp when the current window resets
`Retry-After`	Seconds to wait before retrying

Key Management

Deactivation — Keys can be deactivated from Settings. Deactivated keys are immediately rejected.
Rotation — Create a new key, migrate your integration, then deactivate the old key. There is no in-place rotation.

Best Practices

Never expose your key in client-side code or version control. Use environment variables or a secrets manager.
Respect rate limits. Read the Retry-After header and implement exponential backoff.
Rotate keys periodically and immediately if you suspect a leak.

​Overview

​Obtaining an API Key

​Authenticating Requests

​Header Reference

​Error Responses

​401 — No Key / Invalid Key

​429 — Rate Limited

​Key Management

​Best Practices