Docs
Knowledge API & MCP · Reference

Authentication

The two ways a caller proves who it is: a user JWT or a service key.

Every call to the Ontology Layer is authenticated. There are exactly two ways a caller proves who it is: a user JWT or a service key. This page documents both precisely enough to reproduce a working call.

The API is served by the Chiron Ontology Layer (FastAPI, currently version 2.0.0). A missing or invalid credential returns:

http
401 Unauthorized
{ "detail": "Authentication required: provide a Bearer JWT or X-API-Key" }

User JWT — Authorization: Bearer

An end-user session token, issued by Supabase, HS256-signed. Present it as a bearer token:

http
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVC...

The token is verified against the shared SUPABASE_JWT_SECRET with the authenticated audience. The claims that matter are sub (the user id) and email. A user principal is resolved from the token and the request is scoped to what that user can see.

Service key — X-API-Key

A shared secret for service-to-service calls, validated by direct comparison against the configured key:

http
X-API-Key: <INTERNAL_SERVICE_KEY>

A service principal is not tied to a single user; tenancy for a service call is enforced by the project_id in the path (and, upstream, by whatever checked the user's access before making the call).

Which one to use

  • Building a user-facing feature? Forward the user JWT.
  • Building a backend or an MCP integration that calls the Ontology Layer? Use the service key. The MCP server itself does exactly this: it authenticates *its* user with a bearer token, but calls the Ontology Layer with X-API-Key, because the Ontology Layer validates service keys, not user-issued JWTs.

The difference between the two principals is detailed in Principals & scope.

Next: Knowledge API.