---
title: "Developer API quickstart"
section: "Developer Platform"
canonical_url: "https://support.buildwithhq.com/api/quickstart.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Developer API quickstart

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

## In brief

- **Time:** About 10 minutes
- **First check:** Auth context
- **Secret storage:** Environment or protected file

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.

Tip

Start with a read-only client. Add write, webhook, connector, AI, or installed-service scopes only when the integration has a tested reason to use them.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/api/quickstart.html).