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

# Authentication

> Learn how to authenticate with the Monk API

# Authentication

The Monk API uses API keys to authenticate requests. You can create and manage API keys from your [Settings page](https://app.monk.com/settings).

## Environments

Monk runs production and sandbox as separate instances with separate accounts and API keys.

| Environment    | API URL                        | Dashboard                  |
| -------------- | ------------------------------ | -------------------------- |
| **Production** | `https://api.monk.com`         | `https://app.monk.com`     |
| **Sandbox**    | `https://api-sandbox.monk.com` | `https://sandbox.monk.com` |

<Warning>
  A sandbox API key does not work against production endpoints, and a production
  API key does not work against sandbox endpoints.
</Warning>

## API Key Format

API keys follow this format:

```text theme={null}
mk_live_<48 hex characters>
```

Your API key grants access to your organization's data. Keep it in a secrets manager or environment variable, and never expose it in client-side code or a public repository.

## Making Authenticated Requests

Include your API key in the `Authorization` header as a Bearer token:

```bash theme={null}
curl -X GET "https://api.monk.com/v1/customers" \
  -H "Authorization: Bearer mk_live_your_api_key"
```

## Scopes

API keys can be limited to the operations an integration needs:

| Scope             | Description                  |
| ----------------- | ---------------------------- |
| `*`               | Full access to API endpoints |
| `customers:read`  | Read customer information    |
| `customers:write` | Create and update customers  |
| `invoices:read`   | Read invoice information     |

## Error Responses

### Missing or Invalid Authorization

```json theme={null}
{
  "error": {
    "message": "Missing or invalid Authorization header. Use: Authorization: Bearer <api_key>",
    "code": "UNAUTHORIZED"
  }
}
```

### Invalid, Revoked, or Expired API Key

```json theme={null}
{
  "error": {
    "message": "Invalid API key",
    "code": "UNAUTHORIZED"
  }
}
```

### Insufficient Permissions

```json theme={null}
{
  "error": {
    "message": "API key does not have the required permission: customers:read",
    "code": "FORBIDDEN"
  }
}
```

## Rate Limiting

The Monk API applies rate limits per IP address. When a client exceeds a limit, the API returns `429 Too Many Requests`:

```json theme={null}
{
  "error": {
    "message": "Rate limit exceeded. Please retry after some time.",
    "code": "RATE_LIMITED"
  }
}
```

Use exponential backoff for retries and cache read responses when appropriate.

## Best Practices

<AccordionGroup>
  <Accordion title="Store keys securely">
    Use environment variables or a secrets manager. Never commit API keys to
    version control.
  </Accordion>

  <Accordion title="Use minimal scopes">
    Grant only the scopes required for an integration's work.
  </Accordion>

  <Accordion title="Rotate keys regularly">
    Revoke old keys and create replacements, especially if you suspect a key may
    have been compromised.
  </Accordion>

  <Accordion title="Review key activity">
    Check the Last Used timestamp in Settings to identify unused or suspicious
    keys.
  </Accordion>
</AccordionGroup>