Authentication

Authenticate to the SEAOTTER control plane with Authorization: Bearer <token>. Scripts, MCP, and CI use a SEAOTTER access key (so_…). The signed-in dashboard uses a Clerk session JWT. Hermes runtime credentials on each agent are a separate secret — do not put api_server_key in MCP config. Every authenticated control-plane request uses:

Authorization: Bearer <token>

SEAOTTER accepts two bearer types on the same header.

SEAOTTER access keys (`so_…`)

Use for: scripts, CI, SDKs, MCP (SEAOTTER_API_KEY), and the interactive playground on this docs site.


Create	`POST /api/v1/api-keys` (workspace admin) while signed into the web app, Connect, or Settings
Shape	`so_` + random secret; returned once in `secret`
Scope	Bound to the organization / personal workspace that created the key
Rights	Treated as org admin for mutate routes on that org
Transport	Same value as `Authorization: Bearer so_…` and MCP `SEAOTTER_API_KEY`
Revoke	`DELETE /api/v1/api-keys/{id}`

curl -sS "$SEAOTTER_API/api/v1/me" \
  -H "Authorization: Bearer $SEAOTTER_API_KEY"

Do not put API keys in frontend JavaScript or public repos.

Use with MCP

The @ryanseaotter/mcp-server package reads the key from the MCP server environment:

SEAOTTER_API_KEY='so_…'

See Connect from chat for Claude, Cursor, and Codex config snippets. Never commit the key into .cursor/mcp.json in a shared repo — use a local or user-level config.

Clerk session JWT

Use for: the SEAOTTER web app at seaotter.dev only.


Issuer	`https://clerk.seaotter.dev` (RS256 via JWKS)
Org claims	Nested `o.id` / `o.rol` when an organization is active
Mutate routes	Require `org:admin` (members are read-only)
Users	Created JIT on first successful JWT (`sub` → `users.clerk_id`)

Clerk cookies and short-lived session tokens are not for scripts or the docs playground. Generate an API key instead.

What not to mix up

Credential	Surface
SEAOTTER access key (`so_…`)	`/api/v1/` Bearer and* MCP `SEAOTTER_API_KEY`
Clerk JWT	SEAOTTER web → API
Hermes runtime credential (`api_server_key`)	Per-agent Hermes `/v1` on `*.agents.seaotter.dev` — revealed/fetched after `so_…` auth

Errors

Missing or invalid bearer → 401 with {"detail":"…"}. See Errors.

Get started

Connect from chat

Concepts

SEAOTTER access keys (`so_…`)

Use with MCP

Clerk session JWT

What not to mix up

Errors

​SEAOTTER access keys (so_…)

​Use with MCP

​Clerk session JWT

​What not to mix up

​Errors

SEAOTTER access keys (`so_…`)

Use with MCP

Clerk session JWT

What not to mix up

Errors