Reference · API Keys

API Keys

API keys let your applications call the Esy API without a browser session — runs, artifacts, and costs work exactly as they do for you, because a key acts as your account. Create and manage keys from app.esy.com → Settings.

How keys work

A key is a bearer secret with the prefix esy_sk_. Esy stores only a hash — the full secret is shown once, at creation. Send it on every request:

Authenticate a requestbash

curl https://api.esy.com/v1/runs \
  -H "Authorization: Bearer $ESY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"templateId": "generate-research-report", "intake": {"topic": "Desalination costs"}}'

Requests authenticated with a key behave as your user account: the same permissions, the same workspaces, the same runs list you see in the dashboard.

Workspace binding

A key created with a workspaceId is hard-restricted to that workspace:

Binding	Behavior
`Account-wide`	Acts across every workspace you belong to; unscoped runs land in your personal workspace.
`Workspace-bound`	Runs and artifacts default INTO the bound workspace, and every other workspace is forbidden (403) — even ones you belong to.

Bind keys for production clients

Give each application its own workspace-bound key. If a key ever leaks, the blast radius is one workspace and one revocation — not your whole account.

Endpoints

Key management requires a user session (dashboard login) — a key cannot create or revoke keys.

POST/v1/api-keysCreate a key (secret revealed once). Max 25 active keys.

GET/v1/api-keysList your keys — names, prefixes, usage; never secrets.

DELETE/v1/api-keys/{id}Revoke immediately. Revoked keys remain listed for audit.

POST /v1/api-keysjson

{
  "name": "my-app-backend",
  "workspaceId": "b4c5d6e7-f8a9-4b0c-8d1e-2f3a4b5c6d7e"
}

201 — the only response that ever contains the secretjson

{
  "id": "key-1a2b3c4d",
  "name": "my-app-backend",
  "keyPrefix": "esy_sk_a1b2c",
  "workspaceId": "b4c5d6e7-f8a9-4b0c-8d1e-2f3a4b5c6d7e",
  "lastUsedAt": null,
  "revokedAt": null,
  "createdAt": "2026-07-03T21:15:00.000Z",
  "secret": "esy_sk_a1b2c3…full-secret-shown-once…9f0e"
}

Security best practices

One key per client. my-app-backend, ci, local-dev — so revocation is surgical and last used tells you what is actually alive.
Environment config only. Keys belong in your deployment platform’s secret storage — never in code, git history, client-side JavaScript, or logs.
Bind production keys to a workspace. Containment by default.
Rotate on any suspicion. Create the replacement first, deploy it, then revoke the old key — zero downtime.
Watch “last used”. A key that hasn’t been used in months shouldn’t exist.