Developer Platform

Authentication and API clients

Use isolated draft credentials for unpublished page JSON and an explicit live credential for publication and production operations.

BuildWithHQ separates who is calling from what that caller is allowed to do. Human users use normal app or Builder Console sessions. Server-to-server integrations use one-time-displayed credentials created for one SaaS app.

Four client classes, three bearer schemes

The generated OpenAPI JSON and YAML attach these schemes per operation. Code generators can therefore distinguish draft authoring, app-level production access, and user-delegated access instead of treating every bearer token as interchangeable.

Draft and live are different credential classes

Use a bwk_draft_ credential while a developer, CLI, or coding agent edits unpublished page JSON. Draft credentials can receive only pages.draft.read and pages.draft.write; they cannot read live tenant data or publish. When the draft has been reviewed, deliberately switch the trusted server to a bwk_live_ credential with pages.publish. Publication names the exact draft-history ID and expected live version, so it cannot silently publish a newer or different draft.

# Draft key: save unpublished JSON
PUT /v1/apps/{saasAppId}/page-drafts/Home

# Draft key: validate and capture pageHistoryId + pageVersion
POST /v1/apps/{saasAppId}/page-drafts/Home/validate

# Live key: the explicit release boundary
POST /v1/apps/{saasAppId}/pages/Home/publish

Development uses the production contracts

This is not a stub or mock mode. An unpublished page can bind forms, checkboxes, lists, uploads, and action buttons to the same reviewed API operations and stored procedures used after publication. The server still enforces application, user, DataRole, location, revision, and action scope on every call. Switching to the live key grants release authority; it does not replace the backend or change the component contract.

API clients

An API client is a non-human application identity. Each client has a name, an application boundary, an active/revoked state, and an explicit set of allowed scopes. The raw secret is generated securely and shown only when the client is created or rotated; the platform stores a non-reversible verification form rather than keeping the raw secret for later display.

• Create a separate client for each integration or environment.
• Give it only the scopes it needs.
• Rotate credentials without editing the integration's logical identity.
• Revoke a compromised or retired client immediately.
• Never place server credentials in public browser JavaScript.

Current public scopes

First-class module routes add 48 registered least-privilege scopes in the form modules.<module-key>.read and modules.<module-key>.write. Use the exact requiredScopes value in catalog/operations.json or the API route explorer instead of constructing a scope from a page label.

Scopes are only the first gate

A scope such as records.read means the client may ask to read records; it does not mean every record becomes visible. The API still applies the application's server-side record, DataRole, location, and capability rules appropriate to that identity.

Human sessions

When a human-facing application calls the API on behalf of a signed-in user, the gateway uses that verified user context. UI decisions can hide unavailable actions for convenience, but the server repeats authorization on every request.

OAuth connections are provider credentials, not API identity

The OAuth connection endpoints let an app connect to a registered external provider using authorization code + PKCE. They do not replace the BuildWithHQ API credential that authenticates the caller to the gateway.

Capability review: 2026-09-14. For exact current technical availability, use the generated API Map and first-class module inventory.