Multi-region - BuildPass API

Overview

BuildPass operates separate tenant environments in Australia and the United States. Each of your client’s BuildPass accounts is hosted in one of these regions. Use the appropriate region identifier to connect to each client’s tenant.

Available regions

Region	Region Code	Location
Australia (Default)	`au1` or omitted	Sydney, Australia
United States	`us1`	Ohio, United States

Usage

Setting the region

To route your requests to a specific client’s region, include the X-BuildPass-Region-Id header in your API requests:

curl -X GET "https://api.buildpass.global/builders" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-BuildPass-Api-Version: v1" \
  -H "X-BuildPass-Region-Id: us1"

Default behavior

If the X-BuildPass-Region-Id header is:

Not provided: Defaults to Australia (au1)
Unrecognized value: Defaults to Australia (au1)

This ensures backward compatibility with existing integrations.

External API integrations should continue to use https://api.buildpass.global with the region header or default Australia routing described here. Regional OAuth hosts such as https://api.au.buildpass.global are for BuildPass AI MCP connector setup, where MCP clients cannot reliably provide BuildPass region headers.

How it works

The region selects both the tenant database and where the API handler executes: Australia requests run in Sydney (syd1), and United States requests run in Cleveland, Ohio (cle1). This keeps database work close to its data for all resource endpoints, including builders, projects, site access, timesheets, attachments, photos, meetings and phone calls. Public URLs, request bodies, authentication and permission checks stay the same. The internal /regions/au/* and /regions/us/* paths are implementation details; integrations should continue using the documented public endpoints. Health checks and middleware CORS preflight responses do not need tenant execution routing. OAuth uses the same placement when the region is known from the request. Global MCP token, refresh, revocation, session and userinfo requests can instead carry their region in a credential or session identifier. Those values provide execution hints only: the OAuth handler still validates credentials, signatures, scopes and session ownership. Initial global MCP discovery and registration can involve both regions and default to Australia when no single region has been selected. Multipart upload endpoints use a routing-only middleware pass without parsing their bytes and keep their existing audit exemption. Other middleware audit creation keeps its existing behavior and database ownership. Handler execution placement does not relocate existing data or change the documented fallback behavior when a regional database is not configured.

Maintaining execution routing

The route inventory is generated from app/api/**/route.ts, including OAuth discovery routes. After adding or removing an endpoint, run bun run routes:generate; development startup also regenerates it. bun run test and bun run build reject a stale inventory so new endpoints cannot silently miss regional routing. New catch-all or route-group shapes require explicit router support before the check passes. Regional entrypoints reuse the existing handlers and their authentication wrappers. Their Vercel function placement is pinned by the per-function regions settings in vercel.json; preferredRegion alone is insufficient in this deployment. The shared entrypoints use Node.js and dynamic execution. Next.js route configuration exports on imported handlers (such as maxDuration) do not configure the shared entrypoints; execution budgets come from the regional function configuration and platform defaults. Runtime logs emit Regional request complete with the execution region, selected data region, route template, method, status and handler duration. Route templates omit resource identifiers, and request bodies and credentials are not logged by the dispatcher. After deploying a routing change, verify AU and US requests against these runtime logs; a passing local test cannot prove Vercel placement.

Examples

OAuth token request (US region)

curl -X POST "https://api.buildpass.global/oauth/token" \
  -H "Content-Type: application/json" \
  -H "X-BuildPass-Api-Version: v1" \
  -H "X-BuildPass-Region-Id: us1" \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "grant_type": "client_credentials",
    "scope": "read:builders",
    "audience": "https://api.buildpass.global"
  }'

Australia region (default)

If you don’t specify a region, requests automatically use the Australia data centre:

curl -X GET "https://api.buildpass.global/builders" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-BuildPass-Api-Version: v1"

United States region

To use the US data centre, add the region header:

curl -X GET "https://api.buildpass.global/builders" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-BuildPass-Api-Version: v1" \
  -H "X-BuildPass-Region-Id: us1"

Need help?

If you’re unsure which region a client’s account is hosted in or have questions about implementing multi-region support in your integration, please contact your BuildPass account manager or reach out to our support team at support@buildpass.com.au. For preview integration runs, set CHECKLY_ENABLE_PREVIEW_INTEGRATION_TESTS=true and point ENVIRONMENT_URL at the exact deployment. Use isolated seeded fixtures, TEST_CLIENT_ID/TEST_CLIENT_SECRET for AU, and TEST_US_CLIENT_ID/TEST_US_CLIENT_SECRET plus EXTERNAL_API_US_BUILDER_ID for a separate US fixture. Do not reuse an AU builder ID in US requests. The US variables remain optional for existing environments with mirrored test credentials.

​Overview

​Available regions

​Usage

​Setting the region

​Default behavior

​How it works

​Maintaining execution routing

​Examples

​OAuth token request (US region)

​Australia region (default)

​United States region

​Need help?

Overview

Available regions

Usage

Setting the region

Default behavior

How it works

Maintaining execution routing

Examples

OAuth token request (US region)

Australia region (default)

United States region

Need help?