Authentication

Principle

The API expects a bearer token in the Authorization header.

http

Authorization: Bearer km_your_token_here

Where the token comes from

The token is created in the Kitemesh interface, from the API Tokens section.

The token belongs to the active team selected during creation.

Scope and capabilities

An API token combines two controls:

scope policy: which groups, custom models, tools, and resources the token can access
capabilities: whether the token can chat, upload files, or manage configuration objects

Chat endpoints require the chat capability and access to the requested target. Management endpoints require the matching management capability, such as manageSecrets, manageTools, manageResources, uploadFiles, manageCustomModels, or manageGroups.

Good practices

Create one token per integration.
Set an expiration date whenever possible.
Restrict the scope to the exact groups, custom models, tools, and resources that are needed.
Enable only the capabilities required by the integration.
Revoke a token as soon as an integration is no longer required.

Response when the header is missing or invalid

If the bearer header is missing or empty, the API returns 401.

Example payload:

json

{
  "error": {
    "message": "Missing Bearer API token",
    "type": "authentication_error",
    "code": "authentication_error",
    "request_id": "req_123"
  }
}

Authentication for /metrics

GET /metrics can require a dedicated bearer token if protection is enabled on the target environment. If no metrics token is configured, the endpoint can be reachable without authentication.

Authentication ​

Principle ​

Where the token comes from ​

Scope and capabilities ​

Good practices ​

Response when the header is missing or invalid ​

Authentication for /metrics ​