Keys and Credentials
The five credentials a CortexDB pilot or customer handles, what each one is for, and where it comes from.
Self-hosted CortexDB is for customers
Self-hosted releases from 0.9.0 on, including the one these docs describe, are available to customers through the customer portal, with a company license; talk to us to become one. The last public release, 0.8.21, is on cortexdb.ai/download. To use this release today without running a server, start on CortexDB Cloud.
A self-hosted CortexDB involves five different credentials. They are not interchangeable: each one is refused where another is expected.
| Credential | Usually in | Where it comes from | What it is for |
|---|---|---|---|
| Agent key | CORTEXDB_KEY | customer.cortexdb.ai, Agent keys (a signed-in person makes it) | Downloading releases and reading the docs, CortexHelper and MCP on the portal. Never sent to your CortexDB server: a server refuses it. |
| Company license | CORTEX_LICENSE | The release page's commands, or GET /api/license with an agent key | Letting your server run. Needed once; the server keeps it and renews it (Your license). |
| Server API key | CORTEX_API_KEY | You choose it (the installer makes one when you pick an API key) | The operator credential for a networked server: Authorization: Bearer <key> on every request. Not needed on a server that only listens on its own machine with CORTEX_INSECURE_NO_AUTH=1. |
| Application credentials | Your application's config | Minted by your server, one per application or user | What your applications send instead of the server API key, narrowed to their scopes and capabilities (Security & Compliance). |
| Provider key | OPENAI_API_KEY or CORTEX_EMBEDDING_API_KEY | Your embedding provider | Embeddings only. It stays on your server. Not needed with local Ollama. |
Never share any of them in a chat, a ticket, a screenshot or a log. When you send diagnostics to
CortexDB, replace each value with <redacted>; we never need one to help.
Downloading with scripts and agents
Any HTTP client works with the portal if it sends Authorization: Bearer <agent key>: curl, wget, Python
requests, Node fetch. The portal's own answers carry the header X-CortexDB-Origin: portal, and its
errors are JSON with a code to branch on:
code | Meaning |
|---|---|
AUTH_REQUIRED (401) | No key, or the key isn't valid or was revoked. |
NO_ACCESS (403) | The key is valid but the account's access has ended. |
RETIRED (410) | A release from before licenses; download a newer one. |
NOT_FOUND (404), RATE_LIMITED (429), UNAVAILABLE (503) | As named; UNAVAILABLE is worth retrying. |
A refusal without X-CortexDB-Origin came from the network between you and the portal, not from your
key. Python's urllib is the usual case: its default User-Agent is turned away. Set one that names your
tool, and follow redirects (downloads answer 302 to a short-lived link):
import urllib.request
req = urllib.request.Request(
"https://customer.cortexdb.ai/d/latest/linux-amd64",
headers={"Authorization": f"Bearer {key}", "User-Agent": "my-agent/1.0"},
)