> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monaco.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

## 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.

```text theme={null}
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:

```bash theme={null}
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.

```json theme={null}
{
  "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

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