Authentication

The Monk API uses API keys to authenticate requests. You can create and manage API keys from your Settings page.

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`

A sandbox API key does not work against production endpoints, and a production API key does not work against sandbox endpoints.

API Key Format

API keys follow this format:

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:

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

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

Invalid, Revoked, or Expired API Key

{
  "error": {
    "message": "Invalid API key",
    "code": "UNAUTHORIZED"
  }
}

Insufficient Permissions

{
  "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:

{
  "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

Store keys securely

Use environment variables or a secrets manager. Never commit API keys to version control.

Use minimal scopes

Grant only the scopes required for an integration’s work.

Rotate keys regularly

Revoke old keys and create replacements, especially if you suspect a key may have been compromised.

Review key activity

Check the Last Used timestamp in Settings to identify unused or suspicious keys.

Get Started

Core Concepts

Webhooks

Authentication

Authentication

Environments

API Key Format

Making Authenticated Requests

Scopes

Error Responses

Missing or Invalid Authorization

Invalid, Revoked, or Expired API Key

Insufficient Permissions

Rate Limiting

Best Practices

​Authentication

​Environments

​API Key Format

​Making Authenticated Requests

​Scopes

​Error Responses

​Missing or Invalid Authorization

​Invalid, Revoked, or Expired API Key

​Insufficient Permissions

​Rate Limiting

​Best Practices

Authentication

Environments

API Key Format

Making Authenticated Requests

Scopes

Error Responses

Missing or Invalid Authorization

Invalid, Revoked, or Expired API Key

Insufficient Permissions

Rate Limiting

Best Practices