Skip to main content

Auth for developers

DIC separates who the product is from who the human is. Mix them up and either everything breaks with 401 — or worse, you leak company-wide data.

Three actors​

ActorProves itself withTypical code
Browser userSession cookie or Bearer token against your app / Control Plane loginNextAuth, hosted login
Product (machine)X-Service-SecretServer env
Viewer on a machine callX-Plexon-User-Id plus the secretBFF after session resolve

The contract version header pins the wire:

X-Plexon-Contract-Version: 2026-05-plexon-federation-v3

Path A — browser session​

Use this for GraphiQL (non-prod), human API tokens, and Control Plane UI flows.

  1. User signs in.
  2. Browser calls your same-origin BFF or the Control Plane with a session/Bearer.
  3. No service secret in JavaScript bundles.

Path B — product BFF (most integrations)​

Use this for almost every product integration.

  1. User signs in to your app.
  2. Your server maps the session to a DIC user id.
  3. Your server calls the Control Plane with service secret + contract + user id.
import { buildFederationHeaders, FEDERATION_CONTRACT_VERSION } from '@chbrdk/plexon-federation'

const headers = buildFederationHeaders({
contractVersion: FEDERATION_CONTRACT_VERSION,
serviceSecret: process.env.PLEXON_SERVICE_SECRET!,
userId: dicUserId,
})

await fetch(`${process.env.PLEXON_BASE}/api/platform/provisioning/accessible-collections`, {
headers,
})

Validate credentials (REST)​

POST /api/auth/validate-credentials checks login material against the Control Plane. Prefer using it from a server route. Response shapes live in the SDK Zod schemas and the OpenAPI download.

GraphQL auth​

Same rules. Viewer fields such as me need a session/Bearer or service + actor headers. Service secret alone is not enough.

See GraphQL reference for a me example.

What you must never do​

  • Ship PLEXON_SERVICE_SECRET to the browser
  • Re-use one “god” user id for every customer
  • Skip the contract version header “because it worked yesterday”
  • Treat a 200 from an unauthenticated probe as success (it should not happen on viewer routes)

What usually goes wrong​

StatusMeaningWhat to check
401Not authenticated / missing actorSecret, contract, user id
403Authenticated but not allowedMembership / entitlement
409 / 422Body or state conflictZod-validate with the SDK before retrying

Next: Collections and access · Quickstart