Authentication

The KeeperHub API supports two authentication methods. They are not interchangeable: their accepted scopes differ. See Endpoint scope for the rules.

Session Authentication

For browser-based applications, authentication is handled via Better Auth session cookies. Users authenticate through the standard login flow at app.keeperhub.com.

API Key Authentication

For programmatic access, use API keys in the Authorization header:

curl -H "Authorization: Bearer kh_your_api_key" \
  https://app.keeperhub.com/api/workflows

Key Types

KeeperHub has two types of API keys:

Creating API Keys

1. Navigate to Settings in the KeeperHub dashboard
2. Select “API Keys”
3. For organization keys (kh_), switch to the Organisation tab
4. Click “Create New Key”
5. Copy the key immediately. It will only be shown once.

Key Security

• Keys are hashed with SHA256 before storage
• Only the key prefix is stored for identification
• Revoke keys immediately if compromised

Endpoint scope

Session authentication is accepted everywhere. API keys (kh_) are accepted only on organization-scoped endpoints, the ones whose action and result depend on the caller’s organization rather than on the individual user behind the key. Wallets, billing, and spending caps are all attached to the organization, so a key that authorizes on-chain spend or billable usage is necessarily organization-scoped.

Accepted on API keys

Endpoints whose semantics are organization-scoped accept kh_ keys:

• Workflow CRUD and execution: /api/workflows, /api/executions, /api/execute
• Integrations: /api/integrations
• Projects, tags, public tags, supported chains
• Organization-scoped billing and analytics
• Organization management (e.g. renaming an organization)
• Organization API keys (GET /api/keys, DELETE /api/keys/{keyId}); creation requires session
• Address book entries (organization-scoped)

Session-only

Endpoints that act on a user account, hold credential material, or sit on a human approval boundary require session authentication. API keys are rejected with 401:

• User-account operations: profile mutation (PATCH /api/user), password change, account deactivation, forgot-password
• Per-user preferences: RPC preferences
• Wallet write operations: provisioning, deletion, withdrawal, fee estimation, switching the active signing wallet, retrieving or refreshing the user share, and private-key export
• Authentication primitives: creating organization API keys (POST /api/keys), creating/listing/deleting personal webhook keys (/api/api-keys/*), AI Gateway OAuth flows
• Human-in-the-loop wallet approvals: agentic-wallet linking and approve/reject endpoints
• Per-user state: workflow drafts, workflow ratings, leaving an organization

If you have a use case for session-only behavior over an API key, open an issue describing it. The boundary is deliberate: it keeps a leaked API key from escalating into account control or wallet drainage.

Webhook keys

Workflow webhook triggers (POST /api/workflows/{workflowId}/webhook) accept only user-scoped (wfb_) keys. The route reads the Authorization header directly; session cookies are not consulted, and kh_ keys are rejected with 401. The wfb_ key must belong to the same user that owns the target workflow; a key created by another member of the same organization is rejected with 403. Webhook executions are attributed to the individual triggering user rather than to the organization, which is why the user-binding is enforced.

Deactivated accounts

Deactivating a user account from the dashboard immediately revokes the credentials that user holds, across every supported auth method:

• Sessions are deleted server-side. The user is signed out everywhere they were logged in.
• Organization API keys (kh_) the user created are soft-revoked (revokedAt is stamped). Subsequent requests with those keys return 401.
• MCP OAuth tokens for the user are rejected at the next request, even if their TTL has not yet elapsed.

There is currently no reactivation flow. If a deactivated user wants to come back, they sign up again and provision new credentials.

Webhook Authentication

For webhook triggers, use a user-scoped key (wfb_) with the workflow-specific webhook URL:

POST /api/workflows/{workflowId}/webhook
Authorization: Bearer wfb_your_api_key