Authentication

Every request, except GET / and GET /health, must carry your service's API key in the x-api-key header. The key identifies your service; your service determines which Mantle project pays for the call.

Sending the key

curl https://api.llm.vovix.io/v1/usage \
  -H "x-api-key: $LLM_API_KEY"

A missing or unknown key is rejected by API Gateway before it reaches the API, with a bare 403 body of {"message":"Forbidden"}. A key that exists but doesn't follow the naming convention below gets 401 UNAUTHORIZED.

Keys belong to an app

A key is named llm::<role>::<app>::<email> and its customerId is the app — for example llm::admin::pixora::luandevpro@gmail.com with customerId pixora. When a request arrives, the API reads the key's name and customerId (not its value) and looks the app up in its registry: that decides which Mantle project the call is billed to and whose daily budget it spends.

The role follows the email the key was issued to — admin for the Vovix admin, user for anyone else — and picks the request limits. An app can hold several keys; to rotate, ask the Vovix admin for a new key, switch your app to it, then have the old one disabled.

Why each service has its own project

Amazon Bedrock Mantle attaches every inference to a project, and its CloudWatch metrics carry a Project dimension. That is the only way to split tokens and spend by service when every Vovix product shares one AWS account. So the API never uses a shared project: it resolves your key to your service's project and sends that project with the request.

The projects are owned by this API's infrastructure stack and are retained if the stack is deleted, so a redeploy can't silently start a new cost history.