Skip to main content

​
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 completely separate instances with separate accounts and API keys.
Monk APIMonk Events APIDashboard
Productionapi.monk.comevents-api.monk.comapp.monk.com
Sandboxapi-sandbox.monk.comevents-api-sandbox.monk.comsandbox.monk.com
Sandbox and production are isolated instances with separate data and API keys. A sandbox API key will not work against production endpoints, and vice versa.
Use the environment dropdown in each API reference page to switch between production and sandbox base URLs.

​
API Key Format

API keys follow this format: 
mk_live_<48 hex characters>
For example: mk_live_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6
Your API key grants access to your organization’s data. Keep it secure and never expose it in client-side code or public repositories.

​
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 created with specific scopes to limit their access:
ScopeDescription
*Full access to all endpoints
customers:readRead customer information
customers:writeCreate and update customers
invoices:readRead invoice information
contracts:readRead contract information
contracts:writeCreate and cancel contracts
plans:readRead plan information
plans:writeCreate plans
meters:readRead meter information
meters:writeCreate meters
pricing:readRead pricing configurations
pricing:writeCreate pricing configurations
usage:readRead usage data
usage:writeSend usage events

​
Error Responses

​
Missing or Invalid Authorization

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

​
Invalid API Key

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

​
Revoked API Key

{
  "error": {
    "message": "API key has been revoked",
    "code": "UNAUTHORIZED"
  }
}

​
Expired API Key

{
  "error": {
    "message": "API key has expired",
    "code": "UNAUTHORIZED"
  }
}

​
Insufficient Permissions

{
  "error": {
    "message": "API key does not have the required permission: customers:read",
    "code": "FORBIDDEN"
  }
}

​
Rate Limiting

The Monk API enforces rate limits to ensure fair usage and protect the service from abuse. Rate limits are applied per IP address.
EndpointLimitWindowDescription
/v1/eventsUnlimited—High-throughput event ingestion (1M+ events/sec)
All other endpoints100 requests1 minuteStandard rate limit
The Events API is built on dedicated high-throughput infrastructure and is exempt from rate limiting. You can safely send millions of events per second without throttling.

​
Rate Limit Response

When you exceed the rate limit, you’ll receive a 429 Too Many Requests response: 
{
  "error": {
    "message": "Rate limit exceeded. Please retry after some time.",
    "code": "RATE_LIMITED"
  }
}

​
Best Practices for Rate Limits

When you receive a 429 response, wait before retrying. Double the wait time with each subsequent retry (e.g., 1s, 2s, 4s, 8s).
Use batch endpoints like Batch Events to send multiple items in a single request instead of making many individual calls.
Cache read responses (customers, plans, meters) to reduce redundant API calls. These resources change infrequently.
The Pricing Estimate endpoint accepts up to 500 events per request. Batch events together rather than making separate calls per event. For example, if you run a workflow with 100 events, send them all in one request instead of 100 individual requests.

​
Best Practices

Use environment variables or a secrets manager to store your API keys. Never commit them to version control.
Create API keys with only the scopes needed for their specific use case.
Periodically revoke old keys and create new ones, especially if you suspect a key may have been compromised.
Check the “Last Used” timestamp in your Settings to identify unused or suspicious keys.