Skip to documentation
eli.aidocs

API & MCP

Authentication

The programmatic /api/v1 and /api/mcp surfaces accept a Bearer workspace key (eli_sk_) or user key (eli_uk_). Workspace keys bind one workspace. User keys bind an account and an explicit workspace allowlist or all of that user's live memberships.

The bearer key

Send either key kind in the Authorization header:

every machine requestbash
Authorization: Bearer eli_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# or: Authorization: Bearer eli_uk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Shown once, stored hashed

Only the SHA-256 hash and a short display prefix are stored. The raw key is returned exactly once at creation. If you lose it, revoke it and create a new one.

Selecting a workspace with a user key

A user key restricted to one workspace selects it automatically. A multi-workspace or all-workspaces key must send X-Workspace-Id. The server rechecks membership and the owner's live role capability on every call, so removal or demotion takes effect without rotating the key.

Scopes

A key carries a subset of the scopes. A request needs the scope its endpoint requires:

  • agents:run — Start, cancel, approve, and give feedback on agent runs.
  • runs:read — Read run status, output, and traces.
  • kb:read — Read documents, search, and browse the knowledge graph.
  • kb:write — Create and edit documents, entities, and relations.
  • data:read — List data connectors and governed queries.
  • data:run — Execute governed named queries against connected data sources.
  • reports:read — List and read generated reports.
  • reports:write — Generate new report snapshots.

A missing or invalid key returns 401 unauthorized; a valid key lacking the required scope returns 403 insufficient_scope. See Errors & rate limits.

Create a key

  1. Open Settings

    Go to your workspace Settings and find the API keys section.

  2. Name it and pick scopes

    A descriptive name (e.g. "CI runner") and the least-privilege scopes it needs. Default is agents:run and runs:read.

  3. Copy the secret now

    The raw key is displayed once. Store it in your secret manager immediately.

The backing in-app routes (session-authenticated, not Bearer):

POST/api/w/:workspaceId/apikeysSession · owner

Create a key. The response includes the raw secret exactly once.

Request body

namerequiredstringHuman-readable label.
scopesstring[]Subset of ["agents:run","runs:read","kb:read","kb:write","data:read","data:run","reports:read","reports:write"]. Defaults to agents:run + runs:read.
Responsejson
{
  "id": "01J…",
  "name": "CI runner",
  "prefix": "eli_sk_ab12",
  "scopes": ["agents:run", "runs:read"],
  "key": "eli_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

User-owned keys are created and revoked from account settings through /api/account/keys. Requested scopes must be granted by the user's role in every selected workspace; that same capability boundary is re-evaluated at request time.

GET/api/w/:workspaceId/apikeysSession

List keys (metadata only — never the secret): id, name, prefix, scopes, lastUsedAt, createdAt, revokedAt.

DELETE/api/w/:workspaceId/apikeys/:idSession · owner

Revoke a key. Revoked keys immediately fail with 401 on /api/v1.

Verify a key

Any authenticated read confirms the key and its scope. For example:

smoke testbash
curl -s https://your-host/api/v1/runs/does-not-exist \
  -H "Authorization: Bearer $ELI_KEY"
# 404 {"error":"not_found"}  → key is valid and has runs:read
# 401 {"error":"unauthorized"} → key missing/invalid/revoked
# 403 {"error":"insufficient_scope"} → key lacks runs:read

Every keyed run is attributed

Runs started with a key are tagged with its api_key_id. The workspace monthly spend cap and active-run concurrency cap apply to API, UI, and scheduled starts.

Next

With a key in hand, drive agents via Agents & runs (v1), ask dual-cited questions via Structured query, or point an MCP client at the MCP server.