Authentication

The Bizily MCP API supports two authentication methods: API keys for simple integrations and OAuth 2.0 for AI tools that support it.

API Key Authentication

The simplest way to authenticate. Include your API key in the Authorization header:

Bearer tokenbash

curl https://app.bizily.io/api/mcp \
  -H "Authorization: Bearer biz_sk_xxxxxxxxxxxx"

Getting Your API Key

Go to your dashboard
Navigate to Settings → Developer
Copy your API key

OAuth 2.0

For AI tools like Claude Desktop that support OAuth, use the authorization code flow. Tokens start with mcp_.

Authorization Endpoint

GET /api/oauth/authorize

Parameters: response_type, client_id, scope, redirect_uri, state

Token Endpoint

POST /api/oauth/token

Grant types: authorization_code, refresh_token

OAuth token requesttypescript

const response = await fetch("https://app.bizily.io/api/oauth/token", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    grant_type: "authorization_code",
    code: "AUTH_CODE",
    redirect_uri: "YOUR_REDIRECT_URI",
    client_id: "YOUR_CLIENT_ID",
  }),
});

const { access_token, refresh_token, expires_in } = await response.json();

Scopes

Scopes control what your API key or OAuth token can access. Configure scopes in Settings → Developer.

Read Scopes

read:customersSearch and list customers

read:bookingsView bookings and appointments

read:servicesGet service catalog

read:knowledgeSearch knowledge base

read:teamView team members

Write Scopes

write:bookingsCreate and cancel bookings

write:customersUpdate customer data (notes, tags)

write:messagingSend messages to customers

Wildcards

read:*All read permissions

write:*All write permissions

*Full access

Default scopes: New API keys have read-only access by default: read:customers, read:bookings, read:services, read:knowledge, read:team

Rate Limits

Rate Limits by Client Type

Property	Type	Description
`External AI Tools`	`60 req/min`	External AI tools (Claude Desktop, ChatGPT, Cursor). Write operations: 20/min
`Internal Agents`	`300 req/min`	Internal Bizily agent operations. Write operations: 20/min

When rate limited, you'll receive a 429 status code. Wait and retry with exponential backoff.

Error Codes

Error Responses

Property	Type	Description
`VALIDATION_ERROR`	`HTTP 400`	Invalid parameters or schema validation failed
`UNAUTHORIZED`	`HTTP 401`	Missing or invalid authentication
`FORBIDDEN`	`HTTP 403`	Authenticated but insufficient permissions/scopes
`NOT_FOUND`	`HTTP 404`	Resource or tool not found
`RATE_LIMITED`	`HTTP 429`	Rate limit exceeded
`INTERNAL_ERROR`	`HTTP 500`	Server-side error

Error response formatjson

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid parameter: limit must be between 1 and 100",
    "details": {
      "field": "limit",
      "value": 150
    }
  }
}