Skip to main content

​
Recent updates

​
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) 
{
  "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 
{
  "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)
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:

​
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: 
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.

​
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: 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 - 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/<id> - 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 <credentials> 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 - 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/<timesheetId> - Get a specific timesheet by ID
    • Includes associated profile and project information
    • Full timesheet details with approval status
  • GET /timesheets/time-types - Get configured time types for a builder
    • Returns available time categories (e.g., “Regular Hours”, “Overtime”, “Annual Leave”)
  • GET /timesheets/cost-codes - 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: 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.