Developer Platform

Developer API quickstart

Create an app-scoped credential, verify its identity, make a first record request, and retain correlation evidence.

This path proves the three things every integration needs before it performs real work: the API origin is reachable, the credential is bound to the intended SaaS app, and the requested scope is authorized.

1. Create an API client

In the Developer Console, open the SaaS app and create an API client with only the scopes needed by the integration. Copy the one-time credential into a secret manager or protected environment variable. BuildWithHQ does not show the raw value again.

# PowerShell
$env:BWHQ_API_CREDENTIAL = "bwk_live_..."

# Bash
export BWHQ_API_CREDENTIAL="bwk_live_..."

2. Verify app-bound identity

curl --fail-with-body   -H "Authorization: Bearer $BWHQ_API_CREDENTIAL"   https://api.buildwithhq.com/v1/apps/<saas-app-id>/auth/context

Require the returned SaaS app ID to match the one your integration expects. Keep the returned correlation ID with deployment or test evidence.

3. Discover objects, then search

curl --fail-with-body   -H "Authorization: Bearer $BWHQ_API_CREDENTIAL"   https://api.buildwithhq.com/v1/apps/<saas-app-id>/objects

curl --fail-with-body   -X POST   -H "Authorization: Bearer $BWHQ_API_CREDENTIAL"   -H "Content-Type: application/json"   -d '{"page":1,"pageSize":25,"sort":"created_desc"}'   https://api.buildwithhq.com/v1/apps/<saas-app-id>/objects/work-orders/records/search

4. Use a CLI profile for repeat work

bwhq auth profile add --name development   --saas-app-id <saas-app-id>   --credential-env BWHQ_API_CREDENTIAL   --set-current
bwhq doctor --json
bwhq auth login --json

A profile stores only metadata and a reference to the external credential source. It never stores or prints the bearer value.