Authentication

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

Authorization: Bearer swh_live_xxxxxxxxxxxxxxxxxxxxxxxx

Create and revoke keys on the Access tokens page in Swarmhit (the API keys card). Keys start with swh_live_. 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 and can use every endpoint on it; there are no narrower scopes. A key does not expire: it works until it is revoked, and revoking it takes effect immediately. A workspace can hold up to 25 keys.

Writes are attributed to the user who created the key. The few actions that touch billing (buying or cancelling mailboxes, reading what they cost) also need that user to be an owner or admin of the paying workspace (the organization, for a workspace inside one); otherwise they return 403 (see Mailboxes).

A missing or invalid key gets a 401:

{
  "error": {
    "status": 401,
    "code": "unauthorized",
    "message": "The API key is missing or invalid. Pass it as a Bearer token in the Authorization header."
  }
}

The MCP server has its own key (swh_mcp_…): it does not work on the REST API, and REST keys do not work on the MCP server.

One endpoint needs no key: GET /health. 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: 200 when the API and its database are up, 503 when they are not. See Service status for the public status page.

Acting as a workspace in your organization

An organization key (one created in the organization workspace) 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; an empty value or the organization's own id does the same.

The header is only honored for an organization key targeting one of its own workspaces; any other value is rejected with 401, the same response as an invalid key, and never falls back to the key's own workspace. The /workspaces endpoints always manage the key's organization, whatever workspace the header names.

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

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