# Authentication

> Create, send and revoke the organization API keys the MCP server and the REST API use.

Source: https://docs.capaone.com/capaone/mcp-and-api/authentication/  
Product: CapaOne — a separate CapaSystems product; do not apply this page to any other.

Every request to the MCP server and the REST API carries an organization API key in the
`X-Api-Key` header.

## API keys

- A key belongs to exactly one organization and gives read access to that organization only.
- A key is 64 hexadecimal characters.
- A key expires after 30 days, 90 days or 1 year.
- An organization can have several keys, for example one per integration, so you can revoke one
  without breaking the others.
- A revoked or expired key stops working on the next request.

## Create a key

:::note[Before you start]
You need the **Manager** role in the organization. If you don't have it, ask a manager of your
CapaOne organization to create the key for you. See
[Roles and Product Access](/capaone/account-administration/roles-and-product-access/).
:::

1. Sign in to the [CapaOne console](https://dash.capaone.com).
2. Open **Users & Organization**, from the landing page or the account menu.
3. On the organization the key is for, select **Edit**.
4. Open the **API Keys** tab.
5. Enter a **Key name** that says what uses the key, for example `Claude Desktop` or
   `Inventory export`.
6. Choose when the key **Expires after**.
7. Select **Create API Key**.
8. Select **Copy**.

The key appears in the list with the status **Active**. Store it in your integration's
configuration or a secret store.

## Revoke a key

In the same **API Keys** tab, select **Revoke** next to the key and confirm. The key stops working
immediately and stays in the list as **Revoked**, so you can see who created it and when it was
revoked.

## Sending the key

Put the key in the `X-Api-Key` header of every request:

```http title="HTTP"
GET /api/organizations/123456/mcp/device/search HTTP/1.1
Host: mcp.capaone.com
X-Api-Key: 3f9a…c27e
```

For the MCP server, add the same header to your client's configuration.
[Connect an MCP Client](/capaone/mcp-and-api/connect-an-mcp-client/) has the setup for each client.

## Keeping keys safe

- Treat a key like a password: anyone who has it can read your organization's device data.
- Keep keys in environment variables or a secret store, never in source control.
- Call the API from servers and scripts, not from browser code. The API sends no CORS headers on
  purpose, so browsers block cross-origin calls.
- If a key might have leaked, [revoke it](#revoke-a-key) and create a new one.

## Authentication errors

| Status | Meaning |
|---|---|
| `401` | The `X-Api-Key` header is missing, or the key is unknown, expired or revoked. |
| `403` | The key is valid, but the organization ID in the path is not its organization, or the organization has no active contract. |

:::note[Using several organizations?]
A key never spans organizations. Use one key per organization, with that organization's ID in the
path.
:::