Authentication & workspace scoping

All requests authenticate with an API key passed as a bearer token:

Authorization: Bearer beep_live_xxxxxxxxxxxxxxxxxxxxxxxx

API keys are scoped to either an organization or a single workspace:

• Organization-scoped keys can act on any workspace in the organization and must send the target workspace on every request via the X-Workspace-Id header (a workspace UUID).
• Workspace-scoped keys are pinned to one workspace. The X-Workspace-Id header is optional; when present it must match the key's workspace.

Keys also carry a role (agent < manager < admin). Read endpoints require agent; create/update/delete endpoints require manager or higher.

Base URL & versioning

https://app.beepmessaging.com/api/v1

The API is versioned in the path (/api/v1). Breaking changes ship under a new version prefix.

Response envelope

Successful responses wrap the payload in a data object:

{ "data": { "id": "..." } }

Errors use a consistent envelope with a stable machine-readable code. Common codes: validation_error (400), authentication_required (401), forbidden (403), resource_not_found (404), workspace_not_found (404), duplicate_resource (409), rate_limited (429), internal_error (500). Every response includes an X-Request-Id header.

Rate limits

Requests are rate limited per API key. Each response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (a Unix epoch second). On 429 a Retry-After header indicates how many seconds to wait.