Skip to main content
Every request to an /v1/* endpoint must include an Authorization header carrying a Bearer token. The server validates the token before executing any logic, so an invalid or missing header always returns a 401 before your request reaches the memory engine. There are two classes of API key, each granting access to a different set of operations.

​
API Key Types

KeyEnvironment VariableGrants Access To
StandardCORE_API_KEYIngest, search, list, get, and delete operations
AdminCORE_ADMIN_API_KEYGovernance and admin operations (operator actions, audit log)
Use the standard key for all day-to-day agent operations. The admin key is reserved for governance workflows such as triggering operator mutations, accessing the admin audit log, and performing hard deletes. Keep your admin key out of application code entirely and restrict it to privileged infrastructure processes.

​
Sending a Request

Include the key as a Bearer token in the Authorization header on every request: 
curl -X POST https://your-core-url/v1/memories/search \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"query": "user preferences", "scope": {"user": "alice"}}'

​
Local Development Default

When you run AtomicMemory Core locally via Docker without setting CORE_API_KEY, the server automatically accepts local-dev-key as a valid standard token. This makes local testing friction-free without any configuration. 
curl -X POST http://127.0.0.1:17350/v1/memories/search \
  -H "Authorization: Bearer local-dev-key" \
  -H "Content-Type: application/json" \
  -d '{"query": "editor settings", "scope": {"user": "alice"}}'
The default local-dev-key is only safe because the quickstart binds the server to 127.0.0.1. It is never accepted on a production deployment where CORE_API_KEY is explicitly set.

​
Generating a Production Key

Generate a cryptographically random key before deploying to any non-local environment: 
openssl rand -hex 32
Pass the output as CORE_API_KEY (and optionally a separate value as CORE_ADMIN_API_KEY) in your container environment.

​
Error Responses

HTTP StatusMeaning
401 UnauthorizedThe Authorization header is missing or the token is invalid.
403 ForbiddenThe token is valid but lacks permission for the requested operation (e.g., using a standard key to call an admin-only endpoint).
A 401 response body looks like: 
{
  "error": "UNAUTHORIZED",
  "message": "Missing or invalid Authorization header."
}
A 403 response body looks like: 
{
  "error": "FORBIDDEN",
  "message": "This endpoint requires an admin API key."
}
Never embed API keys in client-side JavaScript, mobile app bundles, or any code that ships to end users. Store keys in environment variables or a secrets manager and access them only from server-side processes.