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
| Credential | Acts as | Lifetime | Best for |
|---|---|---|---|
| API key | The user who issued it | Until revoked | Personal scripts, dev tooling |
| OAuth app credentials | The app | Until revoked | Production integrations |
| App + user delegation | The app on behalf of a user | Per-scope expiry | Acting 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:
- Redirect to
/oauth/authorize?client_id=...&redirect_uri=...&scope=read:files,write:notes - Exchange the returned
codefor an access token - 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: appx-consent-granted-by: <user-id>x-consent-scope: read:files,write:notesx-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:
| Environment | BURDENOFF_ENV | Global endpoint | Workspace endpoint |
|---|---|---|---|
| Production (default) | prod | https://graphql.burdenoff.com/global/graphql | https://graphqlworkspaces.burdenoff.com/workspaces/graphql |
| Alpha | alpha | https://alphagraphql.burdenoff.com/global/graphql | https://alphagraphqlworkspaces.burdenoff.com/workspaces/graphql |
| Local | local | http://localhost:4000/global/graphql | http://localhost:4003/workspaces/graphql |
When BURDENOFF_ENV is unset or invalid, the default is prod.
Next steps
- Quick Start
- GraphQL API
- Node SDK — built-in auth helpers
- Python SDK
- CLI Reference