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.

Agent
Explicit autonomous or semi-autonomous actor

Use agent for autonomous or semi-autonomous workers where you want the credential to clearly represent an agent actor.

Principal model
Both machine principals are explicit and scope-limited.

Neither principal implies unrestricted access. Both are machine principals and remain scope-limited.

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 the same write routes as an agent with that scope (for example application create and content updates), without agent binding; agent credentials still require agent binding where the API enforces it.
  • 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 vs agent)
  • 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.
  • Use agent credentials primarily from external or internal workers that run outside the browser.
  • 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