> ## Documentation Index > Fetch the complete documentation index at: https://developer.buildpass.global/llms.txt > Use this file to discover all available pages before exploring further. # Changelog > Latest changes and improvements to the BuildPass API ## Recent updates *** ### June 11, 2026 - Photos API We've added endpoints for integrators to work with BuildPass photo galleries, folders, and uploaded attachment references. #### Attachments * **[POST /builders/\/attachments/upload](/api-reference/builders/attachments/upload)** - Upload one attachment for later resource creation * Requires an authenticated builder request, with no resource-specific scope required * Requires `type=attachment` so BuildPass can route the file to the correct storage family * Returns `{ key, regionId, type }` plus a short-lived signed `imageUrl` * **[POST /builders/\/attachments/bulk-upload](/api-reference/builders/attachments/bulk-upload)** - Upload multiple attachments for later resource creation or upsert * Requires an authenticated builder request, with no resource-specific scope required * Requires `type=attachment`, or per-file `type:0=attachment` fields, so BuildPass can route each file to the correct storage family * For example, returned attachment references can be used as `photos[].imageAttachment` #### Photos * **[GET /builders/\/photos](/api-reference/builders/photos/list)** - List gallery photos for a builder * Filter by project and folder * Returns photo metadata and a short-lived signed `imageUrl` * **[POST /builders/\/photos](/api-reference/builders/photos/create)** - Create a photo attachment * Accepts an uploaded `imageAttachment` reference from the attachment upload endpoint * Supports approved HTTPS `imageUrl` imports for enabled hosts * Stores the image in BuildPass attachment storage * **[GET /builders/\/photos/\](/api-reference/builders/photos/get)** - Get a photo by id * **[PATCH /builders/\/photos/\](/api-reference/builders/photos/update)** - Update photo metadata or move a photo between folders * **[DELETE /builders/\/photos/\](/api-reference/builders/photos/delete)** - Archive a photo #### Photo Folders * **[GET /builders/\/photo-folders](/api-reference/builders/photo-folders/list)** - List photo folders for a builder * **[POST /builders/\/photo-folders](/api-reference/builders/photo-folders/create)** - Create a photo folder for a project * **[GET /builders/\/photo-folders/\](/api-reference/builders/photo-folders/get)** - Get a photo folder by id * **[PATCH /builders/\/photo-folders/\](/api-reference/builders/photo-folders/update)** - Update a folder name or parent folder * **[DELETE /builders/\/photo-folders/\](/api-reference/builders/photo-folders/delete)** - Delete an empty photo folder #### Photo Gallery Sync * **[POST /builders/\/photo-gallery/bulk-upsert](/api-reference/builders/photo-gallery/bulk-upsert)** - Bulk upsert external photo pages into a BuildPass photo folder * Accepts a returned folder id for repeated sends and skips existing photos * Uses `externalSourceId` metadata for idempotency * Returns created, skipped, and failed photo details * Supports deleting photos created for an external source with `DELETE /builders//photo-gallery/bulk-upsert` Photo and folder endpoints use the `read:photos` and `write:photos` scopes. Attachment upload endpoints require authentication but do not require a resource-specific scope. *** ### June 8, 2026 - Meetings API We've added endpoints for integrators to work with BuildPass meetings. #### Meetings * **[GET /builders/\/meetings](/api-reference/builders/meetings/list)** - List meetings for a builder * Filter by project, status, start date, and end date * Supports pagination with offset/limit * Returns meeting title, type, project, schedule, status, agenda, notes, and update metadata * **[POST /builders/\/meetings](/api-reference/builders/meetings/create)** - Create a draft meeting for a builder * Supports ad hoc meetings from external capture products * Optionally links the meeting to a specific project * **[PATCH /builders/\/meetings/\](/api-reference/builders/meetings/update)** - Update a meeting title * Allows external capture products to keep generated meeting names in sync with BuildPass * **[POST /builders/\/meetings/\/start](/api-reference/builders/meetings/start)** - Mark a meeting as running * **[POST /builders/\/meetings/\/end](/api-reference/builders/meetings/end)** - Mark a meeting as completed #### Meeting Notes * **[GET /builders/\/meetings/\/notes](/api-reference/builders/meetings/notes/list)** - List notes synced to a meeting * **[POST /builders/\/meetings/\/notes](/api-reference/builders/meetings/notes/post)** - Create or update a meeting note from an external source * Notes are upserted by `externalSourceId` * Template-backed meetings store synced notes in the meeting template response * Meetings without a template response store synced notes in the meeting notes field These endpoints use the `read:meetings` and `write:meetings` scopes. *** ### April 7, 2026 - Signed profile and builder asset URLs OAuth identity responses now expose signed image URLs for BuildPass profile and company branding data: * `GET /me` now returns `profilePictureUrl` * `GET /me` memberships now return `builderLogoUrl` * `GET /builders` and `GET /builders/{id}` now return `logoUrl` These fields are intended for integrations that want to mirror BuildPass profile photos or builder logos inside their own applications. *** ### January 7, 2026 - Complete OAuth 2.0 Authorization Server We've implemented a full-featured OAuth 2.0 Authorization Server, enabling BuildPass to act as an identity provider for third-party integrations. This comprehensive implementation supports multiple grant types, client types, and security best practices. #### OAuth 2.0 Endpoints BuildPass now provides a complete suite of OAuth 2.0 endpoints: * **`POST /oauth/token`** - Token endpoint for all grant types * Client Credentials Grant (server-to-server) * Authorization Code Grant (user authorization) * Refresh Token Grant (token renewal) * **`GET /oauth/authorize`** - Authorization endpoint for user consent * Interactive consent screen for builders * State parameter for CSRF protection * Support for pre-selecting builders * Secure session management * **`POST /oauth/revoke`** - Token revocation endpoint (RFC 7009) * Revoke access tokens or refresh tokens * Immediate token invalidation * Compliant with OAuth 2.0 security standards #### Grant Types Supported **1. Client Credentials Grant (RFC 6749 Section 4.4)** * Server-to-server authentication without user involvement * Ideal for backend services and automated integrations * Scoped access to builder data based on pre-configured connections **2. Authorization Code Grant with PKCE (RFC 7636)** * User authorization flow with proof key for code exchange * Support for web apps, mobile apps, and SPAs * 10-minute authorization code lifetime * Single-use codes with automatic revocation on reuse * Refresh token rotation for enhanced security **3. Refresh Token Grant (RFC 6749 Section 6)** * Obtain new access tokens without re-authorization * 30-day refresh token lifetime * Automatic token rotation on use #### Client Types **Confidential Clients** * Backend services and servers that can securely store a `client_secret` * Required to authenticate with both `client_id` and `client_secret` * Support for all grant types * HTTP Basic Authentication or request body credentials **Public Clients** * Mobile apps, SPAs, and desktop applications * Authenticate with only `client_id` (no secret required or allowed) * Must use PKCE with Authorization Code flow * Enhanced security through cryptographic proof #### Security Features **PKCE (Proof Key for Code Exchange) - RFC 7636** * Mandatory for all Authorization Code flows * Supports SHA256 (`S256`) and plain (`PLAIN`) challenge methods * Prevents authorization code interception attacks * Generates cryptographically secure code verifiers **Authorization Code Reuse Protection** * Single-use authorization codes * Automatic revocation of all refresh tokens if code is reused * Protects against replay attacks **Refresh Token Rotation** * New refresh token issued on every use * Old refresh token automatically revoked * Prevents token theft and replay attacks **Token Security** * JWT access tokens with HMAC-SHA256 signing * 1-hour access token lifetime * 30-day refresh token lifetime * Unique token IDs (jti claim) for tracking * Cache-Control: no-store headers on token responses **State Parameter Validation** * Required state parameter for CSRF protection * Validated on callback to prevent cross-site attacks **Redirect URI Validation** * Strict matching of registered redirect URIs * Prevents token theft through malicious redirects #### Token Structure **Access Tokens (JWT)** ```json theme={null} { "sub": "integrator_id", "client_id": "client_id", "builder_id": "builder_id", // For Authorization Code flow "iss": "https://api.buildpass.global", "aud": "https://api.buildpass.global", "scope": "read:builders read:subcontractors", "jti": "unique_token_id", "iat": 1234567890, "exp": 1234571490 // 1 hour from iat } ``` **Token Response Format** ```json theme={null} { "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "token_type": "Bearer", "expires_in": 3600, "scope": "read:builders read:subcontractors", "refresh_token": "550e8400-e29b-41d4-a716-446655440000" } ``` #### Available Scopes Granular permission system for controlling API access: * `read:builders` - Access builder information * `read:subcontractors` - Access subcontractor data * `read:projects` - Access project information * `read:insurances` - Access insurance certificates * `read:prequalifications` - Access prequalification documents * `read:contacts` - Access contact information * `read:swms` - Access SWMS documents * `read:timesheets` - Access timesheet data * `read:inductions` - Access induction records Scopes are validated against: 1. Client's allowed scopes (configured per integration) 2. Audience-specific scope requirements 3. Builder connections (for Authorization Code flow) #### User Consent Flow **Authorization Request** ``` GET /oauth/authorize? response_type=code& client_id=YOUR_CLIENT_ID& redirect_uri=https://yourapp.com/callback& scope=read:builders+read:subcontractors& state=RANDOM_STATE& code_challenge=BASE64_CHALLENGE& code_challenge_method=S256 ``` **User Experience** 1. User redirected to BuildPass consent screen 2. Displays requested permissions and integrator information 3. User reviews and approves/denies access 4. Redirect to application with authorization code or error 5. Application exchanges code for tokens **Builder Selection** * Automatic selection for users with single builder access * Builder selection screen for users with multiple builders * Optional `builder_id` parameter to pre-select builder #### RFC Compliance BuildPass OAuth 2.0 implementation is fully compliant with: * ✅ **RFC 6749** - OAuth 2.0 Authorization Framework * Client Credentials Grant (Section 4.4) * Authorization Code Grant (Section 4.1) * Refresh Token Grant (Section 6) * Error response format (Section 5.2) * ✅ **RFC 7636** - Proof Key for Code Exchange (PKCE) * Required for all Authorization Code flows * SHA256 challenge method support * ✅ **RFC 7009** - Token Revocation * Standardized revocation endpoint * Success response regardless of token validity * ✅ **RFC 6750** - Bearer Token Usage * Authorization header format * Cache control headers #### Audit Logging Comprehensive audit trail for all OAuth operations: * Token requests (all grant types) * Authorization requests and approvals/denials * Token revocations * Failed authentication attempts * Includes client ID, IP address, timestamps, and outcomes #### Error Handling Standard OAuth 2.0 error responses: **Authorization Errors** (redirect to client): * `access_denied` - User denied authorization * `invalid_scope` - Requested scopes not allowed * `server_error` - Internal server error **Token Endpoint Errors** (JSON response): * `invalid_request` - Missing or malformed parameters * `invalid_client` - Invalid client credentials * `invalid_grant` - Invalid/expired authorization code or refresh token * `unsupported_grant_type` - Grant type not supported All errors include descriptive `error_description` for debugging. #### CORS Support Full CORS support for browser-based applications: * Preflight request handling (OPTIONS) * Configurable allowed origins * Credential support for secure cookie handling * Headers: `Access-Control-Allow-Origin`, `Access-Control-Allow-Methods`, `Access-Control-Allow-Headers` #### Migration **No action required for existing integrations:** * All existing clients default to **Confidential** type * Existing Client Credentials flow continues unchanged * Existing authentication patterns remain fully supported **New capabilities available:** * Request Authorization Code flow access for user-facing integrations * Request Public client type for mobile/SPA applications * Contact BuildPass support to enable new features #### Documentation Complete documentation available: * [Authentication Overview](/features/authentication) - Client types and Client Credentials flow * [OAuth 2.0 Authorization Code Flow](/features/oauth-authorization-code) - User authorization guide * Example code for multiple languages and platforms * Security best practices for credential storage * Platform-specific integration guides *** ### November 19, 2025 - Multi-Region Database Support We've added multi-region database routing to support clients in both Australia and the United States. #### What's New * **Region-based Routing**: Route API requests to your client's regional tenant using the `X-BuildPass-Region-Id` header * **Supported Regions**: * `au1` - Australia (Sydney) - **Default** * `us1` - United States (Ohio) #### Usage Include the region header in your API requests to connect to your client's tenant: ```bash theme={null} curl -X GET "https://api.buildpass.global/builders" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "X-BuildPass-Api-Version: v1" \ -H "X-BuildPass-Region-Id: us1" ``` Each client's BuildPass account is hosted in one region. Store the region identifier alongside their OAuth credentials in your integration. #### Migration No migration is required for existing Australian clients: * **Australian clients**: Continue without the header (defaults to `au1`) or explicitly add `X-BuildPass-Region-Id: au1` * **United States clients**: Add `X-BuildPass-Region-Id: us1` to all requests for these clients #### Best Practices * Store each client's region identifier with their credentials * Use the same region for token generation and all API requests for a client * When onboarding new clients, confirm their region with BuildPass For detailed documentation, see [Multi-Region Support](/features/multi-region). *** ### November 11, 2025 - New Inductions API endpoints We've added new endpoints to help you integrate with BuildPass induction data: #### Inductions API New endpoints for accessing induction records: * **[GET /subcontractors/\/inductions](/api-reference/subcontractors/inductions/list)** - Get all inductions for workers associated with a subcontractor * Filter by project ID, status, and type * Supports pagination with offset/limit * Returns induction details including type, status, worker, subcontractor * **[GET /builders/\/projects/\/inductions](/api-reference/builders/projects/inductions/list)** - Get all inductions for a project * Filter by status * Supports pagination with offset/limit * Returns induction details including type, status, and worker information * **[GET /builders/\/projects/\/inductions/\](/api-reference/builders/projects/inductions/get)** - Get a specific induction * Supports lookup by **project-specific identifier** (e.g. `5`) or **induction ID** (e.g. `ind_abc123`) * Automatically returns latest version when version history exists * Returns full induction details with worker, subcontractor, project, and responses These endpoints require the `read:inductions` scope and follow the same authentication patterns as other API endpoints. *** ### January 15, 2025 - Subcontractor endpoints improvements Enhanced performance and reliability for subcontractor status data: * **[GET /subcontractors](/api-reference/subcontractors/list)** - List subcontractors * Subcontractor statuses are now properly filtered based on the `projectId` query parameter when provided * Fixed an issue that caused duplicate statuses to appear in responses * **[GET /subcontractors/\](/api-reference/subcontractors/get)** - Get subcontractor * Added support for the `projectId` query parameter to retrieve project-specific status information *** ### June 25, 2025 - OAuth 2.0 authentication enhancements We've enhanced our authentication system to more effectively comply with the OAuth 2.0 standards: #### New features * **HTTP Basic Authentication**: You can now authenticate using HTTP Basic Authentication in addition to the existing request body method * Pass client credentials via the `Authorization: Basic ` header * Credentials should be Base64-encoded in the format `client_id:client_secret` * Request body credentials take precedence when both methods are used #### Changes * **Standardized Token Expiration**: The `expires` field has been renamed to `expires_in`. The value of this field has not changed. * **Enhanced Security**: Improved request validation and error handling. #### Migration guide You must ensure your code properly handles the `expires_in` field. This can be used to determine when a new token is necessary. The `expires` field will be maintained until the 25th of September, 2025. *** ### May 26th, 2025 - New API endpoints #### Timesheets API We've added comprehensive timesheet management endpoints to help you integrate with BuildPass timesheet data: * **[GET /timesheets](/api-reference/timesheets/list)** - Retrieve all timesheets for a builder with filtering options * Filter by project, status, and date range * Supports pagination with offset/limit * Returns timesheet details including hours, notes, time types, and cost codes * **[GET /timesheets/\](/api-reference/timesheets/get)** - Get a specific timesheet by ID * Includes associated profile and project information * Full timesheet details with approval status * **[GET /timesheets/time-types](/api-reference/timesheets/timeTypes)** - Get configured time types for a builder * Returns available time categories (e.g., "Regular Hours", "Overtime", "Annual Leave") * **[GET /timesheets/cost-codes](/api-reference/timesheets/costCodes)** - Get configured cost codes for a builder * Returns project cost codes for timesheet categorization #### SWMS (Safe Work Method Statements) API New endpoints for accessing SWMS documents: * **[GET /subcontractors/\/swms](/api-reference/subcontractors/swms/list)** - Get all SWMS documents for a subcontractor * Filter by project ID and review status * Supports pagination * Returns document metadata and review status * **[GET /subcontractors/\/swms/\](/api-reference/subcontractors/swms/get)** - Get a specific SWMS document * Includes document URL for download * Shows current review status and approval state These endpoints require appropriate scopes (`read:timesheets` and `read:swms`) and follow the same authentication patterns as other API endpoints. *** ## Need help? If you have questions about these changes or need assistance with migration, please contact our support team.