Zum Hauptinhalt springen

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 downloadentities.graphql
SDK stringFEDERATION_GRAPHQL_SDL from @chbrdk/plexon-federation
AccessSame as REST — Auth

Auth reminder​

ModeSend
Browser / BearerSession cookie or Authorization: Bearer …
Product BFFX-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​

SymptomFix
me is null / 401Add viewer auth (session or service + user id)
Works in GraphiQL, fails from productGraphiQL used a browser session; product forgot the actor header
Field missing vs SDLYou are on an older Control Plane — align versions

Next: REST · Collections