The BuildPass API uses OAuth 2.0 Client Credentials Grant for authentication, fully compliant with RFC 6749. This provides secure, token-based authentication for server-to-server integrations.

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