> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpressbot.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How to authenticate to the MCP servers with an API key, and what the key needs.

## What is this?

Both MCP servers authenticate with the same **API key** you use for the Workspace and Platform APIs. The assistant acts as the key's owner, with that person's permissions.

## What can I do here?

* Create or copy your API key
* Send it in the right header
* Understand the extra checks MCP applies

## How to use it

### 1. Get your API key

Open the [Developer Portal](https://docs.xpressbot.org/workspace/developer-portal.md) → **API Keys** and generate or copy your key. Opening the Developer Portal needs the **API Access** permission — ask an administrator to grant it if you can't see **Developer** in the profile menu.

> [!WARNING]
>
> Treat the key like a password. Keep it out of shared files and repositories. If it leaks, regenerate it.

### 2. Send it as a header

Send the key as `Authorization: Bearer <API_KEY>` (preferred) or `X-API-Key: <API_KEY>`. Never put it in the URL.

| Server | Headers |
| - | - |
| **Workspace MCP** | `Authorization: Bearer <API_KEY>` and `X-Channel-Id: <CHANNEL_ID>` (or `?channelId=` for clients that can't set headers) |
| **Platform MCP** | `Authorization: Bearer <API_KEY>` only |

Find your channel ids with **List channels** (the `list_channels` tool, or the Workspace API's channels endpoint). The channel must be one you own or are assigned to — there is no default channel.

### 3. What else is checked

**Workspace MCP**

1. The key's owner has the **API Access** permission.
2. MCP is allowed on your installation and enabled for the platform, **and** the key owner's plan includes **MCP**.
3. The key is used on the address of the platform it belongs to.
4. The channel in `X-Channel-Id` is one the key's owner can reach. If not, the server answers `404` (never `403`), so channel ids can't be guessed.
5. Each tool call needs the permission shown in the [tool catalog](https://docs.xpressbot.org/api-reference/mcp/workspace/tools/overview.md). Tools you lack permission for are simply not offered.

**Platform MCP**

1. The key's owner is a **platform owner** or **superadmin**, and belongs to a platform. Role and platform are re-read on every request and every tool call.
2. There is no plan gate and no platform or channel parameter — the platform is the key owner's own.

Every authentication attempt also counts against an IP-based limit — see [Rate limits](https://docs.xpressbot.org/api-reference/mcp/rate-limits.md).

## Troubleshooting / Technical Notes

* **`401`.** The key is missing, wrong or revoked. Check the `Authorization` header.
* **`403` on the Workspace MCP.** The key's owner lacks the API Access permission, MCP isn't included in the plan or enabled for the installation, or the key is being used on the wrong platform's address.
* **`403` on the Platform MCP.** The key's owner isn't a platform owner or superadmin.
* **`400 channel_required`.** Add the `X-Channel-Id` header (Workspace MCP only).
* **`404` Channel not found.** The channel doesn't exist, or you can't reach it.
* **claude.ai connectors can't connect.** They need OAuth; use Claude Code, Claude Desktop, Cursor or VS Code.

## Related docs

* [MCP introduction](https://docs.xpressbot.org/api-reference/mcp/introduction.md)
* [Errors](https://docs.xpressbot.org/api-reference/mcp/errors.md)
* [API authentication](https://docs.xpressbot.org/api-reference/authentication.md)
* [Developer Portal](https://docs.xpressbot.org/workspace/developer-portal.md)
* [Team](https://docs.xpressbot.org/workspace/team.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.