Skip to main content

Authentication

How developers identify themselves to the platform.

What you'll learn​

  • The three credential types and when each fits
  • How OAuth apps work
  • How delegation (acting on behalf of a user) works

Credential types​

CredentialActs asLifetimeBest for
API keyThe user who issued itUntil revokedPersonal scripts, dev tooling
OAuth app credentialsThe appUntil revokedProduction integrations
App + user delegationThe app on behalf of a userPer-scope expiryActing in a user's context

All credentials are bearer tokens. Send as Authorization: Bearer <token>.

API keys​

A user can issue any number of API keys from Settings → API Keys. The key inherits the user's permissions.

curl -H "Authorization: Bearer $BURDENOFF_TOKEN" https://graphql.burdenoff.com/global/graphql

Don't ship API keys in production code — use OAuth apps.

→ User guide: API keys

OAuth apps​

Register an app at Developer Console → Apps → New App. You'll get a client_id and client_secret.

Client-credentials flow (machine-to-machine)​

curl -sS https://graphql.burdenoff.com/global/oauth/token \
-d 'grant_type=client_credentials' \
-d "client_id=$CID" \
-d "client_secret=$CSECRET"

The returned bearer token represents the app itself (actor type app).

Authorization-code flow (acting on behalf of a user)​

Standard OAuth 2.0 authorization-code flow with PKCE. After the user consents:

  1. Redirect to /oauth/authorize?client_id=...&redirect_uri=...&scope=read:files,write:notes
  2. Exchange the returned code for an access token
  3. The token represents the app plus the user (delegation)

Delegation​

When an app calls the API with a delegated token, the gateway forwards extra headers:

  • x-actor-id: <app-id>
  • x-actor-type: app
  • x-consent-granted-by: <user-id>
  • x-consent-scope: read:files,write:notes
  • x-consent-granted-at: <iso8601>
  • x-consent-expires-at: <iso8601>

The audit log records both the app and the on-behalf-of user.

→ User-facing: App delegations

Environment selection​

Auth tokens work against all environments, but the token issuer and API gateways differ. Set BURDENOFF_ENV to select the default endpoints used by SDKs and the CLI:

EnvironmentBURDENOFF_ENVGlobal endpointWorkspace endpoint
Production (default)prodhttps://graphql.burdenoff.com/global/graphqlhttps://graphqlworkspaces.burdenoff.com/workspaces/graphql
Alphaalphahttps://alphagraphql.burdenoff.com/global/graphqlhttps://alphagraphqlworkspaces.burdenoff.com/workspaces/graphql
Locallocalhttp://localhost:4000/global/graphqlhttp://localhost:4003/workspaces/graphql

When BURDENOFF_ENV is unset or invalid, the default is prod.

Next steps​