EESI uses Clerk for user authentication (Google and email sign-in). Enabling it is a runtime configuration change — set a few environment variables and restart. The prebuilt eesiai/eesi-api and eesiai/eesi-ui images work as-is; you do not need to rebuild or build from source, because the backend serves the Clerk publishable key to the browser at runtime via /v1/health.
Until Clerk keys are configured, browser sign-in is unavailable (the sign-in endpoints return 503), but API-key access keeps working — you can still call the REST API, SDKs, and MCP server with an sk-eesi-... key.

​
How it works

  1. The backend reads CLERK_SECRET_KEY (and optionally CLERK_PUBLISHABLE_KEY, CLERK_JWT_KEY, CLERK_AUTHORIZED_PARTIES) from its environment.
  2. /v1/health returns the publishable key, which is public by design.
  3. The UI’s server runtime (middleware and SSR) uses CLERK_PUBLISHABLE_KEY and CLERK_SECRET_KEY directly, so both must also be set on the ui service.
  4. The backend verifies Clerk session tokens on every request — networklessly when CLERK_JWT_KEY is set, otherwise via Clerk’s API.

​
Prerequisites

A Clerk application. Create one in the Clerk dashboard and:
  1. Enable the Google and Email sign-in options.
  2. Enable Organizations (EESI scopes agents, keys, and billing to organizations).

​
Step 1 — Collect your Clerk credentials

From your application in the Clerk dashboard (API Keys page), gather:

​
Step 2 — Configure the backend (api)

Set these on the api service. Add them to the environment: block of the api service in your docker-compose.yaml: The shipped docker-compose.yaml already forwards CLERK_SECRET_KEY and CLERK_PUBLISHABLE_KEY from your .env to both the api and ui services (the UI runs server-side Clerk middleware that needs them). Set them in .env:
.env
CLERK_JWT_KEY is optional but recommended in production: with the JWKS public key (PEM) set, the backend verifies session tokens networklessly instead of calling Clerk’s API on each request.

​
Step 3 — Restart and verify

Recreate the containers so they pick up the new environment:
Confirm the backend reports Clerk and serves the publishable key:
Then open the UI. The sign-in page should present Google and email sign-in via Clerk.

​
Environment variable reference

CLERK_SECRET_KEY is the only secret here. Keep it out of any client-visible config and never bake it into an image. The publishable key is public by design — the backend deliberately serves it to the browser so Clerk can initialize at runtime.
Superuser promotion via SUPERUSER_EMAILS only trusts a verified Clerk email — the backend never promotes an account off an unverified address. Keep email verification enabled in your Clerk instance (the default). If you disable it, an attacker could register a listed address without proving ownership, and while the backend still requires verification, you lose that first line of defense.

​
Running without Clerk

Without Clerk keys the browser dashboard cannot sign in (the UI serves but shows an “authentication not configured” screen, and API-authenticated requests return 503), but the platform is still usable programmatically: any existing sk-eesi-... API key continues to authenticate the REST API, WebSocket connections, SDKs, and MCP server.