Skip to content
Documentation

Authentication

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

API keys

Section titled “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

Section titled “Create a key”
  1. Sign in to the CapaOne console.
  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

Section titled “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

Section titled “Sending the key”

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

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 has the setup for each client.

Keeping keys safe

Section titled “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 and create a new one.

Authentication errors

Section titled “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.