GraphQL reference
GraphQL on the DIC Control Plane is query-oriented composition over Collections, users, bindings, and members. REST + the database remain the system of record for writes that are not exposed in GraphQL yet.
| Endpoint path | /api/graphql |
| SDL download | entities.graphql |
| SDK string | FEDERATION_GRAPHQL_SDL from @chbrdk/plexon-federation |
| Access | Same as REST — Auth |
Auth reminder
| Mode | Send |
|---|---|
| Browser / Bearer | Session cookie or Authorization: Bearer … |
| Product BFF | X-Service-Secret + X-Plexon-User-Id + contract version |
Service secret alone is not enough for me and other viewer fields.
HTTP shape
POST /api/graphql
Content-Type: application/json
{ "query": "…", "variables": { } }
Example — who am I?
query Me {
me {
id
email
name
}
}
curl -sS -X POST "${PLEXON_BASE}/api/graphql" \
-H 'content-type: application/json' \
-H "X-Service-Secret: ${PLEXON_SERVICE_SECRET}" \
-H 'X-Plexon-Contract-Version: 2026-05-plexon-federation-v3' \
-H "X-Plexon-User-Id: ${PLEXON_USER_ID}" \
-d '{"query":"query Me { me { id email name } }"}'
Expect 401 if you omit auth — that is the correct failure.
Example — Collection by id
query Collection($id: ID!) {
collection(id: $id) {
id
name
}
}
Only Collections the actor may access should resolve. Treat unexpected null + auth errors as “no grant”, not as “retry with a broader secret”.
SDL-first docs
The portal ships the SDL file for offline reading and codegen. A full Magidoc HTML tree can be generated from the same SDL in the control-plane repo (federation:graphql:docs) when you need browsable type pages; pin that output to the same commit as this portal build when you publish both.
What usually goes wrong
| Symptom | Fix |
|---|---|
me is null / 401 | Add viewer auth (session or service + user id) |
| Works in GraphiQL, fails from product | GraphiQL used a browser session; product forgot the actor header |
| Field missing vs SDL | You are on an older Control Plane — align versions |
Next: REST · Collections