Authentication

CLANKER.NET 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: All users can create API keys. BYOK accounts get up to 1 key, PAYG accounts get up to 10 keys, Based Mode accounts get unlimited keys.

Using API Keys

MCP Clients (Streamable HTTP — recommended):

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

REST API:

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

API Key Limits

• BYOK accounts: up to 1 API key
• PAYG accounts: up to 10 API keys
• Based Mode accounts: unlimited API keys
• Keys can be revoked anytime from the app
• Keys are tied to your user account and inherit your subscription mode

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 Apple, Google, or enterprise SSO in the app
2. The app receives an auth token automatically
3. For direct API use, tokens are returned in the auth response

Using Auth Tokens

curl https://clanker.net/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://clanker.net/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://clanker.net/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 accepted but not currently enforced. All authenticated requests have full access to the user’s account.

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

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.