Authentication

This page explains how to send your API key with each request, what a key can reach and how to manage keys. Memory integrations and the MCP server use project API keys.

The API reference documents every operation your project API key can call. Manage projects, keys and memory policies in the dashboard.

Send the key

Put the key in the Authorization header, after Bearer:

Request headers

POST /v1/memories/context HTTP/1.1
Host: api.alvia.ai
Authorization: Bearer sk-mem-...
Content-Type: application/json

Send every request over HTTPS to https://api.alvia.ai.

What a key can reach

• One project. A key belongs to the project it was created in. Every request with it reads and writes that project’s memories, and no other project’s.
• Every published memory operation. A key can store, read, forget and give feedback on every memory in its project, in any scope.
• Memories only. A key reaches memories; projects, keys and usage stay in the dashboard.

Every key in a project shares the project’s memory policy. Giving a service its own key lets you revoke that credential independently. See Memory policies.

Keep keys safe

• Call Alvia from your server only. A key in a web page, a mobile app or a browser extension can be copied by anyone who uses it. The API serves server-side calls, so keys never need to reach a browser.
• Keep keys in environment variables or a secret manager. Never put a key in source control, logs, error reports or tickets.
• Use one key for each service and environment. If a key leaks, you revoke one key and the others keep working.
• Revoke a key as soon as it may have leaked. Anyone with the key can read and change the project’s memories.

Manage keys

You create and revoke keys in the dashboard, inside a project.

• Create. Give the key a name that says where it is used, such as “billing-service production”. The full key is shown only once. Alvia stores only a hash of it and keeps its last four characters, so you can tell keys apart.
• Revoke. A revoked key stops working on its next request. Only account admins can revoke keys.
• Expiry. Choose an expiration when creating a key, or choose a key that never expires. An expired key stops authenticating, so replace it before expiry. Rotate keys without an expiration on your own schedule.

Rotate a key

1. Create a new key in the same project.
2. Deploy the new key to every service that used the old one.
3. Check that no requests still use the old key.
4. Revoke the old key.

When authentication fails

A missing, malformed, revoked or expired key, or a key whose project was deleted, gets a 401 response:

Response

{
  "type": "https://alvia.ai/docs/errors/#unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "The request does not include a valid authenticated user",
  "instance": "/v1/memories",
  "code": "unauthorized"
}

For security, the response does not say which part failed. Check, in order:

1. The header is Authorization, and its value is Bearer followed by the key.
2. The key is complete, with no spaces or line breaks copied with it.
3. The key has not expired or been revoked, and its project still exists.

Related pages

• Security
• Production checklist
• Errors