Automation

PrivacyFlow exposes two API surfaces — the public client API for messaging and the account-management API for dashboard operations.

PrivacyFlow exposes two distinct API surfaces. They share a deployment but not an auth model, a path prefix, or a use case. Mixing them up is the most common integration mistake — read this page before wiring anything.

The two API surfaces

Use the public API when you want messages to flow — that’s what the MCP server, Agent Zero channel, and n8n node talk to.

Use the account management API when you want to do what the dashboard does — list apps, create credentials, configure webhook delivery, pay an invoice, manage a group — without clicking through the UI. Every dashboard action maps to one route under /dashboard/api/dashboard/*.

What this section covers

• API reference — every /dashboard/api/dashboard/* route, the resource it touches, and the body/response schema.
• Authentication — the session-cookie-to-X-Session-Token model, the 8s timeout, and the allowlist-only path surface.
• Apps — list, create, update, delete, and toggle messengers via /dashboard/api/dashboard/apps*. This is the canonical way to display all your apps.
• Credentials — issue API keys and webhook tokens via /dashboard/api/dashboard/credentials*.
• Webhook auth — per-app delivery config and the webhook auth wizard, via /dashboard/api/dashboard/apps/update.
• Crypto payments — invoice lifecycle, supported assets, paid-tier rate-limit lift.
• Notifications — messenger/webhook-failure/security alerts via /dashboard/api/dashboard/notification-preferences.
• Groups — group membership, admin promote/demote, invite links, via /dashboard/api/dashboard/group/*.

The BFF proxy model (account management API only)

The account-management API is a backend-for-frontend. The browser hits /dashboard/api/dashboard/<endpoint> with the HTTP-only session cookie. The dashboard proxy reads the cookie, forwards it as the X-Session-Token header to the backend, and applies an 8-second timeout plus an allowlist of routes.

Browser (logged into dashboard)
   │  Cookie: session=xyz123  (HTTP-only)
   ▼
Dashboard proxy  →  /dashboard/api/dashboard/<endpoint>
   │  • Reads the session cookie
   │  • Injects X-Session-Token: <cookie value>
   │  • Enforces the route allowlist
   │  • Applies an 8-second timeout
   │  • Checks Origin on POST/PUT/DELETE
   ▼
PrivacyFlow backend  →  /dashboard/<endpoint>
   │
   ▼
JSON response  →  sanitized and forwarded to the browser

The proxy enforces an allowlist of routes. Every writable route maps to a fixed /dashboard/* backend path. The proxy has no ?url= passthrough, no OPTIONS handler, and no CORS — the account API is same-origin only.

Consequences for your integration

• Don’t call /api/v1/messages/send from a browser session. The public API is server-to-server only.
• Don’t call /dashboard/api/dashboard/apps with an API key. The account API requires the session cookie; API keys are scoped to the public messaging API only.
• To script account-management operations, capture the session cookie from a logged-in dashboard session and reuse it for the lifetime of your script. Re-authenticate on 401 — cookies expire.
• The two APIs read from different stores. The public API reads DenoKV (api_keys, apps, users/*/tier). The account API reads from the backend’s own backing store. Changes via the account API (e.g., creating a credential) propagate to the public API; changes via the public API never affect the account API.