engine9 API keys

engine9 API keys provide generic authentication for non-session HTTP callers, including public forms, inbound integrations, data routes, and the Task API. Use this skill to create, scope, rotate, revoke, or integrate e9key_ and e9publickey_ credentials. MCP and console users authenticate through sessions instead; API keys are for machines and other HTTP clients.

Quick reference

Rule: Never send an e9key_ or e9publickey_ credential to MCP.

Concepts

There is one key model; scopes decide what a key can do. The Task API is one consumer, not the definition of a key.

Typical callers:

• Public signup and payment forms (public, people:write, …)
• Site / inbound HTTP (people:write, tables:write, data:read)
• Machine integrations, including scheduling work (tasks:read, tasks:schedule)

MCP (POST /mcp) stays on Firebase / session / localdev. That path is distinct. Keys remain the common mechanism for HTTP APIs: Authorization: Bearer e9key_… (or e9publickey_…) plus X-ENGINE9-ACCOUNT-ID. Do not send e9key_ to MCP, and do not send MCP session tokens to key-authenticated routes.

Humans manage keys through MCP apiKey. Machines use the issued secret on HTTP.

Storage and verification always go through @engine9/core (SqlApiKeyStore in the account api_key table). MCP does not invent a second store. Only the SHA-256 hash is retained; plaintext is returned once on create and rotate.

Workflow

Rule: Do not schedule SQLWorker.createApiKey (or rotate/revoke) via MCP task; the plaintext key would land in task run output.

CLI fallbacks (no MCP): server WorkerRunner e9 sqlworker createApiKey / listApiKeys / updateApiKey / revokeApiKey / rotateApiKey on a server account, or core npx e9 create-api-key on a core-only site (@engine9/core bin/e9.js — not the same binary as server bin/e9; see @engine9/core README “The e9 CLI”).

Scopes

The scope list is the permission model. The same key type covers forms, inbound, reads, and tasks; attach only the scopes that surface needs. Keys must list scopes at creation. Empty scopes deny every check. admin grants all scopes. Prefix follows scopes at create/rotate: public → e9publickey_…, otherwise e9key_…. Changing scopes later does not change an existing key's prefix — rotate if you need the other prefix.

Rule: Grant only the scopes required by the calling surface; empty scopes deny every permission check, while admin grants all scopes.

Constants: SCOPES from @engine9/core. Canonical list for UIs: MCP apiKey command: catalog → scopes[].

A public signup or payment form typically needs:

public,people:write

A partner that discovers flows and schedules tasks needs:

tasks:read,tasks:schedule

MCP examples

Catalog (build the permissions form from this — do not hardcode scopes):

{ "command": "catalog" }

List:

{ "account_id": "<account_id>" }

Create (plaintext in key, shown_once: true):

{
  "command": "create",
  "account_id": "<account_id>",
  "name": "public-signup",
  "scopes": ["public", "people:write"]
}

Task-API partner (same key model, different scopes):

{
  "command": "create",
  "account_id": "<account_id>",
  "name": "partner-tasks",
  "scopes": ["tasks:read", "tasks:schedule"]
}

Update permissions without rotating:

{
  "command": "update",
  "account_id": "<account_id>",
  "id": "<key_id>",
  "scopes": ["tasks:read"]
}

Rotate / revoke: pass command and id. Rotate copies metadata when omitted.

List returns keys[]. Get/update/revoke return record. None of those include plaintext or key_hash. Create/rotate include plaintext in key once (shown_once: true) — display it and do not write it to files, chat logs, or task output.

Auth

• Managing keys: signed-in MCP user with access to account_id (same gate as sql / task).
• Using keys: Authorization: Bearer e9key_… + X-ENGINE9-ACCOUNT-ID on any HTTP route that verifies layer-1 keys (core site APIs, public forms, Task API, and other scoped endpoints). MCP POST /mcp does not accept e9key_ keys.

CLI (when MCP is not available)

e9 sqlworker createApiKey -a <account_id> --name partner-tasks --scopes tasks:read,tasks:schedule
e9 sqlworker listApiKeys -a <account_id>
e9 sqlworker updateApiKey -a <account_id> --id <key_id> --scopes tasks:read
e9 sqlworker rotateApiKey -a <account_id> --id <key_id>
e9 sqlworker revokeApiKey -a <account_id> --id <key_id>

Core-only (no accounts.d):

npx e9 create-api-key --db sqlite://./engine9.db --name website --scopes admin

Related documentation