Authentication

API keys

Use API keys for server-to-server integrations, scheduled jobs, CRM syncs, and backend services. Generate a key under Settings → API Keys and send it in the Authorization header:

Authorization: Bearer sk_live_...

Keys are scoped to the organization that created them. They can access that organization's projects and the data allowed by its plan.

Treat an API key like a password:

• Store it in a server-side secret manager or environment variable.
• Do not put it in frontend JavaScript, mobile binaries, logs, screenshots, or source control.
• Give each integration its own key so it can be rotated independently.
• Revoke a key immediately if it may have been exposed.

OAuth for MCP

MCP clients authenticate through Bellwork's OAuth flow and send the resulting Bearer access token. Use the canonical MCP endpoint:

https://www.bellwork.ai/api/mcp/bellwork/mcp

The older /api/mcp/school-scout/mcp alias is deprecated and should not be used for new clients.

Errors

• 401 Unauthorized: the token is absent, invalid, expired, or revoked.
• 403 Forbidden: authentication succeeded, but the organization, plan, or project does not allow the requested operation.
• 429 Too Many Requests: wait until the rate-limit reset time before retrying.