Accounts API

Manage accounts and API keys.

Authentication

There are two authentication methods:

Session cookies: set via OAuth2/PKCE sign-in through KF Auth (handled by better-auth at /api/auth/*), used by the web UI
API keys: Authorization: Bearer ul_..., used by apps and scripts

User accounts are created automatically on first sign-in via KF Auth (OAuth2/PKCE). There are no local signup or login endpoints.

API keys have three scopes: read, write, admin. The scope is stored in key metadata and translated to permissions server-side. A key can optionally be scoped to a single collection.

GET /api/accounts/me

Auth: session or API key (any scope)

Get the authenticated account.

Response 200

{
  "id": "uuid",
  "slug": "jdoe",
  "type": "user",
  "displayName": "Jane Doe",
  "email": "[email protected]",
  "createdAt": "2026-01-15T00:00:00.000Z"
}

GET /api/accounts/:slug

No auth required

Get public profile for any account.

Response 200

{
  "id": "uuid",
  "slug": "knowledge-futures",
  "type": "org",
  "displayName": "Knowledge Futures",
  "createdAt": "2026-01-15T00:00:00.000Z"
}

POST /api/auth/api-key/create

Auth: session or API key (any scope)

Create a new API key. The raw key is returned only once. Managed by better-auth's apiKey plugin.

Request

{
  "name": "my-sync-script",
  "metadata": { "scope": "write" },
  "prefix": "ul"
}

Response 200

{
  "id": "uuid",
  "key": "ul_a1b2c3d4e5...",
  "name": "my-sync-script",
  "metadata": { "scope": "write" },
  "prefix": "ul"
}

GET /api/auth/api-key/list

Auth: session or API key (any scope)

List all API keys for the authenticated account. Returns id, name, start, permissions, metadata, createdAt, and expiresAt. The raw key is not included.

POST /api/auth/api-key/delete

Auth: session or API key (any scope)

Revoke an API key.

Request

{ "keyId": "uuid" }

Response 200

{"ok": true}