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.

​
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://app.monk.com/api/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
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"
  }
}

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