Authentication

clanker.engineer supports multiple authentication methods depending on your use case.

Authentication Methods

API Keys (Recommended for MCP)

API keys are the recommended authentication method for MCP clients and external integrations.

Getting an API Key

All credentials live on a single screen: Settings → External Agents. From there you have two paths:

1. Pair a CLI agent (recommended for Hermes, OpenClaw, Claude Code, your own) — tap ACTIVATE, enter the 8-character code your agent prints, approve. The agent receives an API key bound to your active workspace via the device-flow.
2. Name a key manually (for Cursor, VS Code, CI scripts, anything without a built-in pair command) — tap OR NAME A KEY, type a label, hit CREATE. The key is shown once; copy it immediately.

Both paths produce the same ck_… workspace-scoped API key. The External Agents list shows everything you have connected with a heartbeat (ACTIVE / IDLE / DORMANT) based on last-used time, and a one-tap revoke per session.

Note: A key carries your identity, not a plan: it inherits your subscription mode, and every plan needs a card on file before a skill can run (402 PAYMENT_METHOD_REQUIRED until then).

Using API Keys

MCP Clients (Streamable HTTP — recommended):

{
  "mcpServers": {
    "clanker": {
      "url": "https://next.clanker.engineer/mcp/",
      "headers": {
        "x-api-key": "ck_live_xxxxxxxxxxxxx"
      }
    }
  }
}

REST API:

curl https://next.clanker.engineer/api/v1/marketplace/skills \
  -H "x-api-key: ck_live_xxxxxxxxxxxxx"

API Key Limits

• Keys can be revoked anytime from the app
• Keys are tied to your user account and inherit your subscription mode
• How many keys you can hold at once depends on your plan: BYOK 1, PAYG 10, Based Mode unlimited. The keys an app or pod mints for you automatically (a pod’s key, or a key issued to a third-party app you approved) and revoked or expired keys do not count.
• Creating a key past the limit returns 403 with details.reason: "API_KEY_LIMIT" (and limit, used, mode). Revoke a key or upgrade, then try again. Keys you already hold are never removed.

Auth Tokens (Mobile/REST)

Auth tokens are used by the mobile app and direct REST API integrations.

Getting an Auth Token

Auth tokens are issued during authentication:

1. Sign in with GitHub in the app — or with your organisation’s OIDC provider, on a deployment configured for it. New accounts are created through GitHub or the deployment’s OIDC provider only; there is no email/password sign-up, and other social logins can only sign in to an account that already exists
2. The app receives an auth token automatically
3. For direct API use, tokens are returned in the auth response

A sign-in with an email address the provider has not verified never links to an existing account. The first time a provider signs in to an account that already exists for that email, the sign-in is refused unless the provider confirms the email is verified.

Using Auth Tokens

curl https://next.clanker.engineer/api/v1/artifacts \
  -H "x-auth-token: YOUR_AUTH_TOKEN"

OAuth 2.0

For third-party applications that need to act on behalf of users.

Authorization Endpoints

Authorization Flow

1. Redirect user to authorization URL:

https://next.clanker.engineer/oauth/authorize?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://yourapp.com/callback&
  scope=read write&
  state=random_state_string

2. User approves access
3. User is redirected to your callback with a code
4. Exchange code for tokens:

curl -X POST https://next.clanker.engineer/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "AUTHORIZATION_CODE",
    "redirect_uri": "https://yourapp.com/callback",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
  }'

OAuth Scopes

Note: OAuth scopes are enforced. A token can only call routes whose scope it was granted, and a token granted no scopes can call none. apikey:pod lets an app mint a narrowly scoped key for the user; see Agent Permissions.

Security Best Practices

1. Never expose API keys in client-side code - Use server-side requests or MCP clients
2. Rotate keys regularly - Delete unused keys from the app
3. Use environment variables - Store keys in .env files, not in code
4. Monitor usage - Check the app for unusual activity

Error Responses

Every failure is the standard { "error": { "code", "message" } } envelope; branch on error.code, not the message.

Workspace Scoping

Every credential is bound to a workspace. API keys are workspace-scoped at creation. Session auth tokens default to your personal workspace; pass x-workspace-id: <uuid> on individual requests to act in a different workspace. Switching the active workspace for an API key is done via PUT /api/v1/workspaces/current.

External Agents + thread subscription

Once a external agent has paired (device-flow) and stored its API key, the recommended next step is to subscribe to a thread before sending any input. The subscription receives the active agent stream — including chunks from a wake-up sendMessage, tool-call approval requests, and <notification> records pushed by background events (workflow completions, GitHub webhooks). Without an open subscription, the agent only sees responses to its own POST /api/v1/chat/:agentId calls.

# 1. Subscribe (long-lived SSE; reconnect on close with 25s heartbeats).
curl -N -X POST $BASE/api/v1/agents/clanka-01/subscribe-thread \
  -H "x-api-key: $KEY" \
  -d '{"resourceId":"<workspaceId>","threadId":"<threadId>"}'

# 2. Send messages in parallel.
curl -X POST $BASE/api/v1/agents/clanka-01/send-message \
  -H "x-api-key: $KEY" \
  -d '{"resourceId":"<workspaceId>","threadId":"<threadId>","message":"Status?"}'

The same x-api-key authenticates both the subscription and the message endpoints. See /skill.md “Thread subscription & messaging” for the full surface.