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
| Actor | Proves itself with | Typical code |
|---|---|---|
| Browser user | Session cookie or Bearer token against your app / Control Plane login | NextAuth, hosted login |
| Product (machine) | X-Service-Secret | Server env |
| Viewer on a machine call | X-Plexon-User-Id plus the secret | BFF 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.
- User signs in.
- Browser calls your same-origin BFF or the Control Plane with a session/Bearer.
- No service secret in JavaScript bundles.
Path B — product BFF (most integrations)
Use this for almost every product integration.
- User signs in to your app.
- Your server maps the session to a DIC user id.
- 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_SECRETto 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
| Status | Meaning | What to check |
|---|---|---|
| 401 | Not authenticated / missing actor | Secret, contract, user id |
| 403 | Authenticated but not allowed | Membership / entitlement |
| 409 / 422 | Body or state conflict | Zod-validate with the SDK before retrying |
Next: Collections and access · Quickstart