API Reference

HeadshotMarketing exposes a federated GraphQL API on the Burdenoff Workspaces and Global gateways. All requests go through the gateway; direct service-to-service calls are not supported.

Endpoints

Production

Gateway	URL
Workspace public	https://graphqlworkspaces.burdenoff.com/workspaces/graphql
Global public	https://graphql.burdenoff.com/global/graphql

Alpha

Gateway	URL
Workspace public	https://alphagraphqlworkspaces.burdenoff.com/workspaces/graphql
Global public	https://alphagraphql.burdenoff.com/global/graphql

Local

Gateway	URL
Workspace public	http://127.0.0.1:4003/workspaces/graphql
Global public	http://127.0.0.1:4000/global/graphql

Switch environments with BURDENOFF_ENV. See Environment Selection.

Authentication headers

The gateway validates tokens and injects identity headers. When calling the GraphQL API directly, include:

Header	Required	Description
Authorization	Yes	Bearer <platform-access-token>
x-workspace-id	Yes	Workspace UUID (for workspace gateway calls)
x-workspace-token	Yes	Workspace-scoped token (for workspace gateway calls)

The workspace token is issued by the global auth service after you select a workspace. The CLI and SDKs handle this automatically.

Example request

curl -X POST \
  https://graphqlworkspaces.burdenoff.com/workspaces/graphql \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "x-workspace-id: ${WORKSPACE_ID}" \
  -H "x-workspace-token: ${WORKSPACE_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"query": "query { campaigns { id name status } }"}'

Alpha access (Cloudflare Access)

Alpha endpoints are gated by Cloudflare Access. Automation passes via service-token headers:

curl -X POST \
  https://alphagraphqlworkspaces.burdenoff.com/workspaces/graphql \
  -H "CF-Access-Client-Id: ${CF_ACCESS_CLIENT_ID}" \
  -H "CF-Access-Client-Secret: ${CF_ACCESS_CLIENT_SECRET}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "x-workspace-id: ${WORKSPACE_ID}" \
  -H "x-workspace-token: ${WORKSPACE_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"query": "query { campaigns { id name status } }"}'

Fetch tokens from the dev Key Vault using the CF Access scripts in ~/products/dev/platform/context/cfaccess/.

Schema

The HeadshotMarketing subgraph schema is maintained in wspace-headshotmarketing-svc and published to GraphQL Hive Cloud. The gateway composes it with other subgraphs into a single supergraph.

To inspect the schema locally:

cd ~/products/wspace/headshotmarketing/wspace-headshotmarketing-svc
bun run codegen      # Generates TypeScript types from the schema

Error codes

HTTP	Meaning
200	Success (check errors array for GraphQL-level errors)
401	Missing or invalid Authorization header
403	Missing or invalid workspace token / insufficient RBAC
404	Subgraph not registered (gateway cannot route to HeadshotMarketing)
429	Rate limited

---

For the full platform GraphQL reference, see Burdenoff Platform Docs.