Back to API docs

Using Buildspace API credentials

API credentials are machine credentials issued from the internal admin surface. Use them for system-to-system access to buildspace-api, not for end-user browser sessions.

Recommended header
Use the dedicated machine-token header for system-to-system calls.

Send the secret with X-Buildspace-Api-Token

. The API also accepts Authorization: Bearer <secret>, but the dedicated machine-token header is clearer and avoids confusion with user JWTs.

Service
Infrastructure-style machine consumer

Use service for backend jobs, sync processes, automation, and integrations that act as infrastructure for your organization.

Principal model
Service credentials are explicit and scope-limited.

Service credentials never imply unrestricted access. They remain machine credentials with explicit scope limits.

Scopes control route access
Machine credentials are deny-by-default.

A credential can only access routes that allow its principal and whose required scopes are present on the credential.

  • applications:read allows read access to machine-consumable application routes such as GET /api/v1/application/tokens and GET /api/v1/application/<uuid>/agents (application id in the path; same access pattern as other application-scoped reads).
  • applications:write on a service credential allows application create and content-update routes on the machine-consumable surface.
  • Admin credential management routes are internal-only and are not part of the public machine-consumer surface.
  • User-only routes still require a normal Supabase session token.
One-time secret handling
Treat the raw secret like any other production credential.
  • The raw secret is shown once when the credential is created.
  • Store it immediately in your secret manager.
  • If it is lost or leaked, revoke the credential and create a new one.
Example request
Minimal machine-auth request against buildspace-api.
curl -H "X-Buildspace-Api-Token: <credential_secret>" \
  "{origin}/api/v1/application/tokens?limit=1"
How to validate a credential
Use the admin tester before shipping a credential into automation.

After creation, use the Buildspace Admin Test credentials flow to verify:

  • the observed principal (service)
  • the scopes attached to the credential
  • declared route coverage
  • observed smoke-test results against buildspace-api
Runtime patterns
Choose the runtime intentionally when you put a machine credential into use.
  • Use service credentials primarily from backend jobs, syncs, and other server-to-server infrastructure.
  • Direct browser use of X-Buildspace-Api-Token
     is allowed only from origins included in CORS_ALLOWED_ORIGINS. Even when allowed, prefer backend-mediated use for long-lived machine credentials instead of embedding them in frontend code.
Related references
Open the live API reference or download the contract.
Open API docsDownload OpenAPI JSON