Authentication - BuildPass API

The BuildPass API uses OAuth 2.0 for authentication, fully compliant with RFC 6749. We support two authentication flows:

Authentication Flows

Client Credentials Grant (Server-to-Server)

For server-to-server integrations without user involvement, use the Client Credentials flow. This is ideal for backend services that need to access BuildPass data programmatically. 👉 This page documents the Client Credentials flow.

Authorization Code Grant (User Authorization)

For applications that need user consent and access to data on behalf of specific builders, use the Authorization Code flow with PKCE.

OAuth 2.0 Authorization Code Flow

Learn about user authorization with PKCE for integrator applications.

Client Types

BuildPass supports two types of OAuth 2.0 clients, each designed for different security requirements:

Confidential Clients

Confidential clients can securely store credentials and are required to authenticate with a client_secret. Best for:

Backend services and servers
Server-to-server integrations
Applications running in secure, controlled environments
Services where credentials can be kept private

Authentication: Must provide both client_id and client_secret to obtain access tokens.

Public Clients

Public clients cannot securely store credentials (e.g., mobile apps, single-page applications) and can authenticate without a client_secret. Best for:

Mobile applications (iOS, Android)
Single-page applications (SPAs)
Desktop applications
Browser-based applications

Authentication: Only requires client_id. Must use PKCE (Proof Key for Code Exchange) with the Authorization Code flow for security.

Your client type is determined when BuildPass provisions your integration credentials. Contact BuildPass support if you need to change your client type or are unsure which type you have.

Client Credentials Grant

This flow provides secure, token-based authentication for server-to-server integrations.

Client Credentials Grant is only available for Confidential Clients. Public clients must use the Authorization Code flow with PKCE.

Step 1: Obtain Client Credentials

You need to have the following client credentials:

client_id
client_secret

These credentials should be provided by BuildPass. If you don’t have them, please contact BuildPass support.

Step 2: Generate an OAuth Token

To generate an OAuth token, you need to make a POST request to the /oauth/token endpoint with your client credentials. The request body should include the following parameters:

client_id: Your client ID.
client_secret: Your client secret.
scope: The scopes you want to request access to. Available scopes include read:builders, read:subcontractors, read:prequalifications, read:insurances, read:contacts, read:swms, read:timesheets, read:inductions.
audience: The audience for the token. This should be set to https://api.buildpass.global.
grant_type: The grant type you want to use. This should be set to client_credentials.

API reference

Check out the API reference for our OAuth2 token endpoint.

Example Request

curl --request POST \
  --url https://api.buildpass.global/oauth/token \
  --header 'Content-Type: application/json' \
  --data '{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "scope": "read:builders read:subcontractors read:prequalifications read:insurances",
  "audience": "https://api.buildpass.global",
  "grant_type": "client_credentials"
}'

Alternative: HTTP Basic Authentication

You can also provide client credentials via HTTP Basic Authentication instead of the request body:

curl --request POST \
  --url https://api.buildpass.global/oauth/token \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic base64(client_id:client_secret)' \
  --data '{
  "scope": "read:builders read:subcontractors",
  "audience": "https://api.buildpass.global",
  "grant_type": "client_credentials"
}'

Form Data Support

The endpoint also supports application/x-www-form-urlencoded content type:

curl --request POST \
  --url https://api.buildpass.global/oauth/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'client_id=your_client_id&client_secret=your_client_secret&scope=read:builders&audience=https://api.buildpass.global&grant_type=client_credentials'

Response Format

The token response follows OAuth 2.0 standards:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "expires": 3600 // deprecated, please use expires_in,
  "scope": "read:builders read:subcontractors"
}

Error Responses

Error responses follow OAuth 2.0 RFC 6749 standards:

{
  "error": "invalid_client",
  "error_description": "Invalid client credentials"
}

Common error codes:

invalid_request: Missing or malformed request parameters
invalid_client: Invalid client credentials
invalid_scope: Requested scopes are invalid for the audience
unsupported_grant_type: Grant type not supported

Step 3: Use the Access Token

Once you have the access token, include it in the Authorization header of your API requests as a Bearer token.

Example Authorization Header

Authorization: Bearer YOUR_ACCESS_TOKEN

OAuth 2.0 Compliance Features

Our implementation is fully compliant with OAuth 2.0 standards:

RFC 6749 - OAuth 2.0 Authorization Framework

✅ Client Credentials Grant (Section 4.4)
✅ Standard Token Response Format (Section 5.1)
✅ Standard Error Response Format (Section 5.2)
✅ Client Authentication Methods (Section 2.3.1)

RFC 6750 - Bearer Token Usage

✅ Authorization Request Header Field (Section 2.1)
✅ Cache Control Headers (Section 3)

Additional Security Features

✅ JWT Access Tokens with HMAC-SHA256 signing
✅ Unique Token IDs (jti claim) for token tracking
✅ Encrypted Client Secret Storage
✅ Audience-Specific Scope Validation
✅ Comprehensive Audit Logging

Token Management

Token Lifetime: 1 hour (3600 seconds)
Token Format: JSON Web Token (JWT)
Signing Algorithm: HMAC-SHA256
Security Headers: Cache-Control: no-store, Pragma: no-cache

Token Security Best Practices

Credential Storage

Critical Security Requirements:

Encrypt client secrets at rest - Never store in plain text or environment variables visible in logs
Use secure credential management - Consider using secret managers (AWS Secrets Manager, HashiCorp Vault, etc.)
Encrypt access tokens at rest - Use your platform’s secure storage
Never log credentials or tokens - Treat them as sensitive data
Rotate credentials periodically - Contact BuildPass support for credential rotation

Token Handling

// ✅ GOOD: Secure credential storage (Node.js example)
const AWS = require('aws-sdk');
const secretsManager = new AWS.SecretsManager();

async function getCredentials() {
  const secret = await secretsManager.getSecretValue({
    SecretId: 'buildpass/client-credentials'
  }).promise();
  return JSON.parse(secret.SecretString);
}

// ❌ BAD: Never do this
const CLIENT_SECRET = process.env.CLIENT_SECRET; // Visible in logs
console.log('Secret:', CLIENT_SECRET); // Never log secrets!

Access Token Storage

For applications that cache access tokens:

// ✅ GOOD: In-memory storage with expiration tracking
class TokenManager {
  constructor() {
    this.token = null;
    this.expiresAt = null;
  }

  async getToken() {
    if (this.token && Date.now() < this.expiresAt) {
      return this.token;
    }
    return await this.refreshToken();
  }

  async refreshToken() {
    const response = await fetchNewToken();
    this.token = response.access_token;
    this.expiresAt = Date.now() + (response.expires_in * 1000);
    return this.token;
  }
}

// ❌ BAD: Never store tokens in files or databases without encryption
fs.writeFileSync('token.txt', accessToken); // Insecure!

Network Security

Always use HTTPS - BuildPass API only accepts HTTPS connections
Validate TLS certificates - Don’t disable certificate validation
Use Basic Auth header - Preferred method for client credentials
Don’t include credentials in URLs - Use headers or request body

Monitoring and Auditing

BuildPass provides comprehensive audit logging:

All token requests are logged with client ID and IP address
Failed authentication attempts are tracked
Unusual patterns trigger alerts

We recommend:

Monitor your token usage patterns
Set up alerts for failed authentication attempts
Regularly review access logs
Investigate unexpected token requests

BuildPass API

Features

​Authentication Flows

​Client Credentials Grant (Server-to-Server)

​Authorization Code Grant (User Authorization)

OAuth 2.0 Authorization Code Flow

​Client Types

​Confidential Clients

​Public Clients

​Client Credentials Grant

​Step 1: Obtain Client Credentials

​Step 2: Generate an OAuth Token

API reference

​Example Request

​Alternative: HTTP Basic Authentication

​Form Data Support

​Response Format

​Error Responses

​Step 3: Use the Access Token

​Example Authorization Header

​OAuth 2.0 Compliance Features

​RFC 6749 - OAuth 2.0 Authorization Framework

​RFC 6750 - Bearer Token Usage

​Additional Security Features

​Token Management

​Token Security Best Practices

​Credential Storage

​Token Handling

​Access Token Storage

​Network Security

​Monitoring and Auditing

Authentication Flows

Client Credentials Grant (Server-to-Server)

Authorization Code Grant (User Authorization)

Client Types

Confidential Clients

Public Clients

Client Credentials Grant

Step 1: Obtain Client Credentials

Step 2: Generate an OAuth Token

Example Request

Alternative: HTTP Basic Authentication

Form Data Support

Response Format

Error Responses

Step 3: Use the Access Token

Example Authorization Header

OAuth 2.0 Compliance Features

RFC 6749 - OAuth 2.0 Authorization Framework

RFC 6750 - Bearer Token Usage

Additional Security Features

Token Management

Token Security Best Practices

Credential Storage

Token Handling

Access Token Storage

Network Security

Monitoring and Auditing