Authentication

Every request must carry an API key as a bearer token:

Authorization: Bearer swh_live_xxxxxxxxxxxxxxxxxxxxxxxx

Create and revoke keys under Settings → API & Webhooks in the Swarmhit app. A key's full value is shown only once, at creation, so store it securely. Each key is scoped to the workspace it was created in.

The one exception is GET /health, which needs no key. It reports whether the API is serving and returns no workspace data, so uptime monitors can read a real status code rather than the 401 every other path returns without a key. See Service status for the public status page.

Acting as a workspace in your organization

An organization key can operate on any workspace inside it without a separate key, by naming the target in a request header:

X-Swarmhit-Workspace: <workspaceId>

With the header set, every data endpoint (campaigns, leads, accounts, inbox, and so on) acts on that workspace. Omit it to act on the organization itself.

The header is only honored for an organization key targeting one of its own workspaces; any other value is rejected with 401. The /workspaces endpoints always manage the key's organization regardless of the header.

For the MCP server, append &workspaceId=<workspaceId> to the connection URL instead.

See Organization for managing those workspaces and their sender-seat allocations.