Information
- OpenAPI version:
3.0.3
Overview
Signals DPG API 1.0.0
Section titled “Signals DPG API 1.0.0”Network-aware Signals DPG API — items, actions, events, consent, network fetch, admin.
Unless marked otherwise, operations require authentication via either the apiKeyAuth or sessionAuth scheme (the spec default). Public operations carry no Authorizations section; the four inter-instance peer operations (the three *_local reads and action/perform) use the service-to-service peerAuth scheme instead. Admin and aggregator operations additionally require the x-acting-org-id header (optional on action operations). See docs/operations/integrating-dpgs.md for the full auth model.
Authentication
Section titled “Authentication”apiKeyAuth
Section titled “apiKeyAuth”Service API key used by integrating DPGs (aggregator-dpg, voice-dpg) and other machine clients (apps/api/plugins/auth/auth_middleware.ts). Takes priority over session auth: if present and invalid the request is rejected outright, with no fallback to a session. Routes under /api/v1/admin and /api/v1/aggregator additionally require an x-acting-org-id header identifying the organization the request acts on behalf of — see docs/operations/integrating-dpgs.md.
Security scheme type: apiKey
Header parameter name: x-api-key
sessionAuth
Section titled “sessionAuth”Opaque browser-session cookie issued by the BFF after sign-in, used by the web UI (apps/api/plugins/auth/resolve_browser_session.ts). httpOnly, so script cannot read it; the access and refresh tokens live server-side in Redis and never reach the browser. Checked when x-api-key is absent, before the bearer path. Under AUTH_PROVIDER=betterauth this channel is dormant and the session cookie is better-auth’s own better-auth.session_token instead. Every unsafe method (anything but GET/HEAD/OPTIONS) additionally requires the x-csrf-token header echoing the value from GET /api/v1/auth/session; without it the request is refused with 403 CSRF_TOKEN_INVALID.
Security scheme type: apiKey
Cookie parameter name: sid
csrfToken
Section titled “csrfToken”Per-session CSRF token for the cookie channel, read from GET /api/v1/auth/session and echoed on every state-changing request. A cookie is attached by the browser automatically, so this double-submit token is what a cross-site page cannot supply — it can cause the cookie to be sent but cannot read the response that carries this value. Not required on GET/HEAD/OPTIONS, and not used by the x-api-key or bearer channels.
Security scheme type: apiKey
Header parameter name: x-csrf-token
peerAuth
Section titled “peerAuth”Inter-instance HMAC token (paired with an x-instance-timestamp header), used only by peer Signals instances for the network *_local operations (src/middleware/peer_instance_guard.ts). Not for external callers.
Security scheme type: apiKey
Header parameter name: x-instance-token