Authentication

SoluCortex has two authentication levels: Admin (project management) and API Key (agent operations).

Admin Token

For management operations: create projects, list projects and manage API keys. It is configured as an environment variable on the server.

Header X-Admin-Token: <SOLUCORTEX_ADMIN_TOKEN>

bash

curl -s "$SOLUCORTEX_URL/api/v1/projects" \
  -H "X-Admin-Token: $SOLUCORTEX_ADMIN_TOKEN" \
  -H "Accept: application/json"

🔒 The Admin Token has full access. Never expose it in client code or public repositories.

Project API Key

For agent operations: register memories, fetch context and run semantic search. Each project has its own API keys (prefixed with scx_).

Header Authorization: Bearer scx_<api_key>

bash

curl -s -X POST "$SOLUCORTEX_URL/api/v1/memories" \
  -H "Authorization: Bearer $SOLUCORTEX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ ... }'

Generate an API key

When a project is created, a key is generated automatically. To create additional keys:

From the UI

Project dashboard → New API Key.

Via API (Admin)

bash

curl -s -X POST "$SOLUCORTEX_URL/api/v1/projects/$PROJECT_ID/api-keys" \
  -H "X-Admin-Token: $SOLUCORTEX_ADMIN_TOKEN" \
  -H "Accept: application/json"

⚠️ API keys are only shown in plain text at creation time. After that, only the SHA-256 hash is stored.

Revoke an API key

bash

curl -s -X DELETE \
  "$SOLUCORTEX_URL/api/v1/projects/$PROJECT_ID/api-keys/$KEY_ID" \
  -H "X-Admin-Token: $SOLUCORTEX_ADMIN_TOKEN"

Authentication errors

Code	Reason
`401`	Token missing or invalid
`403`	Valid API key but the project does not match
`429`	Rate limit exceeded - wait before retrying