Authentication.
Three layers — sessions, API keys, and service tokens. Each does one job; together they cover the dashboard, the public API, and the internal hop between gateway and engine.
§ 01Three layers, one identity
Essarion has one account model and three ways to prove you are that account. Which one you use depends on where the request comes from.
- Session cookies for the dashboard and any browser-side surface.
- API keys for everything you build — server-to-server, scripts, integrations.
- Service tokens for the internal hop between the API gateway and the research engine. You will not use these directly; they are documented so you understand the architecture.
§ 02Session cookies
Sessions back the dashboard. After signin we set an HS256-signed JWT in an HTTP-only, secure cookie named essarion_session. The cookie is scoped to .essarion.com, has a seven-day expiry, and is rotated on every signin to limit reuse if a stale token leaks.
Session-authenticated endpoints include the key management routes (/api/keys), the usage analytics (/api/usage), and ownership-checked run timeline reads. You will not normally hit them from a server — they exist to let the dashboard render your account.
curl https://api.essarion.com/api/keys \
-H "Cookie: essarion_session=eyJhbGciOiJIUzI1NiJ9..."§ 03API keys
API keys are the primary public surface. Every server you build, every script, every integration — all of them authenticate with a key. Keys are created in the dashboard under Settings → API keys.
Format
Keys are prefixed with esk_ (Essarion secret key). The full string is shown once at creation; afterwards we store only a SHA-256 hash. There is no way to recover the plaintext if you lose it — you generate a new one and revoke the old.
Passing the key
Two equivalent header formats are accepted. Bearer is preferred because it composes cleanly with HTTP intermediaries.
curl https://api.essarion.com/api/v1/query \
-H "Authorization: Bearer esk_live_a1b2c3d4..." \
-H "Content-Type: application/json" \
-d '{"query": "What is the platform?"}'curl https://api.essarion.com/api/v1/query \
-H "X-API-Key: esk_live_a1b2c3d4..." \
-H "Content-Type: application/json" \
-d '{"query": "What is the platform?"}'Statuses
Each key has a status field with one of three values.
| Status | Meaning |
|---|---|
| active | In use. Authenticates calls and increments last_used_at on each request. |
| revoked | Permanently disabled. Calls return 401 with code KEY_REVOKED. Cannot be reactivated. |
| inactive | Temporarily disabled — e.g. plan suspended. Calls return 401; can be reactivated by clearing the underlying condition. |
Every successful authentication updates last_used_at on the key. The dashboard surfaces this so you can see which keys are still in active rotation and which can be safely revoked.
esk_ keys server-side. Never embed them in a client bundle, browser extension, or mobile app — anything shipped to a user can be extracted. If you need browser-side access, broker calls through your own backend.§ 04Service-to-service tokens
Internally, the API gateway authenticates to the research engine with a long-lived bearer service token plus two identity headers: X-Essarion-User-Id, which carries the user the call is being made on behalf of, and (optionally) X-Essarion-Key-Id, which carries the key id used at the gateway.
You do not see this hop. It is documented so you understand that the gateway never trusts the engine and the engine never trusts an unsigned caller — every internal call carries a service identity and a user identity, and both are checked.
POST /internal/run
Authorization: Bearer svc_xxxx
X-Essarion-User-Id: usr_01HXYZ...
X-Essarion-Key-Id: key_01HXYZ...Service tokens are not issued to customers. If you have a use case that you think needs one — typically a tightly-coupled enterprise integration — talk to us about a dedicated workspace.