> ## 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.
# List site access (planned)
> Proposed worker-project access feed for access-control providers.
This endpoint and its `read:site_access` scope are **planned and not yet available
in production or sandbox**. This page is published for integration design and
partner review. It does not announce API availability or a delivery date.
## Access is an explicit decision
Each grant represents one worker's access to one project. `ACTIVE` permits site
access; `REVOKED` removes it. Revoking access on one project does not revoke access
on another. Induction review may support an explicit grant, but an induction is
not itself an access grant.
The grant ID uses `grant_`, the worker ID uses `wkr_`, and the path requires
`buil_` and `proj_` IDs. A worker keeps the same ID across employer changes.
Removing a subcontractor does not automatically revoke worker access. Providers
must use explicit grant status, not employer status or absence from a list.
## Lifecycle and example
A grant keeps its ID across revocation and regrant. `grantedAt` records the most
recent grant; `revokedAt` is null while active. Revoking a grant retains the row
and advances `updatedAt` so the change remains discoverable.
```json theme={null}
{
"data": [
{
"id": "grant_clgbsb90b001qjy0f0eo1hspp",
"worker": {
"id": "wkr_clgbsb90b001qjy0f0eo1hspp",
"fullName": "Alex Smith"
},
"status": "REVOKED",
"grantedAt": "2026-09-14T23:00:00.000Z",
"revokedAt": "2026-09-15T00:10:00.000Z",
"createdAt": "2026-09-14T23:00:00.000Z",
"updatedAt": "2026-09-15T00:10:00.000Z"
}
],
"meta": {
"totalCount": 1,
"totalPages": 1,
"offset": 0,
"limit": 25
}
}
```
## Proposed polling contract
* Initial synchronization omits `updatedAfter` and `status` and reads all pages.
* Incremental synchronization supplies `updatedAfter` as an exclusive UTC
timestamp (`updatedAt > updatedAfter`) and omits `status` to include revocations.
* Results are ordered by `updatedAt` ascending, then grant ID ascending. Apply updates by grant ID. The final checkpoint protocol must handle equal
timestamps and changes during pagination without skipping records.
* The proposed page size is 25 by default, up to 100, using `offset` and `limit`
and the standard `meta` response. This does not change existing endpoints' limits.
* Changes to embedded worker data, including `fullName`, must also advance the
grant's feed timestamp.
Stable ordering alone does not guarantee a consistent multi-page sync while data
changes. Snapshot/cursor behavior, checkpoint advancement, retry/reconciliation
rules and revoked-record retention must be confirmed before this endpoint is
available. Do not build a production watermark algorithm from this draft alone.
Five-minute access polling is a discussion starting point. Effective revocation
also depends on a successful poll and controller processing; no hard revocation
SLA or offline behavior is committed here.
## Contract decisions still to confirm
The fields above are the proposed grant feed. Employer projection, worker photos
and RFID credentials are separate contract work and are not included in this
response yet. Photo or credential availability must not create or revoke a grant.
Before implementation, confirm deletion and worker-merge reconciliation,
builder offboarding, project archive policy, credential and biometric deletion,
and the final polling consistency rules. Gate activity ingestion is a separate
planned endpoint.
## OpenAPI
````yaml GET /builders/{builderId}/projects/{projectId}/site-access
openapi: 3.0.0
info:
title: BuildPass API
description: >-
Approved integrators can connect to the BuildPass API on behalf of builders
to build connections between a wide range of construction platforms.
version: 1.0.0
servers:
- url: https://api.buildpass.global
description: Production server
security:
- OAuth2: []
paths:
/builders/{builderId}/projects/{projectId}/site-access:
get:
summary: List site access (planned)
description: >-
Planned endpoint: published for integration design; not yet available in
production or sandbox. Returns explicit worker-project access grants,
including revocations. Requires the planned read:site_access scope.
Induction and employer status must not be used to infer access. Final
sync and lifecycle details are subject to partner confirmation.
operationId: getProjectSiteAccess
parameters:
- name: builderId
description: The ID of the builder
in: path
required: true
schema:
type: string
example: buil_clgbsb90b001qjy0f0eo1hspp
- name: projectId
description: The ID of the project
in: path
required: true
schema:
type: string
example: proj_clgbsb90b001qjy0f0eo1hspp
- name: offset
description: >-
The number of items to skip before starting to collect the result
set
in: query
required: false
schema:
type: integer
default: 0
example: 0
minimum: 0
- name: limit
description: >-
Planned page size for this endpoint (default 25, maximum 100).
Existing endpoints retain their documented limits.
in: query
required: false
schema:
type: integer
default: 25
example: 25
maximum: 100
minimum: 1
- name: X-BuildPass-Api-Version
in: header
required: true
schema:
$ref: '#/components/schemas/X-BuildPass-Api-Version'
- name: updatedAfter
in: query
required: false
description: >-
Proposed exclusive UTC lower bound: return grants whose updatedAt is
strictly greater than this timestamp. Omit for initial/full sync.
Poll without a status filter to receive revocations. Final
pagination consistency and checkpoint rules will be confirmed before
availability.
schema:
type: string
format: date-time
example: '2026-09-15T00:00:00.000Z'
- name: status
in: query
required: false
description: >-
Optional status filter for browsing. Omit during synchronization:
filtering ACTIVE would hide revocations.
schema:
type: string
enum:
- ACTIVE
- REVOKED
- name: X-BuildPass-Region-Id
in: header
required: false
description: Builder database region; defaults to au1.
schema:
type: string
enum:
- au1
- us1
default: au1
responses:
'200':
description: >-
Planned response: grants ordered by updatedAt ascending, then id
ascending. Includes ACTIVE and REVOKED when status is omitted.
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedResponseSiteAccess'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
'403':
description: Forbidden
'404':
description: Builder or project not found within the authorized scope.
'429':
description: Too Many Requests
'500':
description: Internal Server Error
security:
- OAuth2:
- read:site_access
components:
schemas:
X-BuildPass-Api-Version:
type: string
example: v1
default: v1
enum:
- v1
description: What API version to use.
PaginatedResponseSiteAccess:
type: object
required:
- data
- meta
properties:
data:
type: array
items:
$ref: '#/components/schemas/SiteAccessGrant'
meta:
$ref: '#/components/schemas/PaginationMeta'
ErrorResponse:
type: object
properties:
errors:
type: array
items:
type: object
properties:
fieldName:
type: string
example: name
message:
type: string
example: This field is required.
SiteAccessGrant:
type: object
required:
- id
- worker
- status
- grantedAt
- revokedAt
- createdAt
- updatedAt
properties:
id:
type: string
pattern: ^grant_.+$
description: >-
Stable grant identifier for one worker-project relationship.
Regranting retains this ID.
example: grant_clgbsb90b001qjy0f0eo1hspp
worker:
type: object
required:
- id
- fullName
properties:
id:
type: string
pattern: ^wkr_.+$
description: Stable worker ID, unchanged by employer changes.
example: wkr_clgbsb90b001qjy0f0eo1hspp
fullName:
type: string
example: Alex Smith
status:
type: string
enum:
- ACTIVE
- REVOKED
description: >-
Explicit access decision for this project. Credential availability
is separate.
grantedAt:
type: string
format: date-time
description: Time of the most recent explicit grant or regrant.
example: '2026-09-14T23:00:00.000Z'
revokedAt:
type: string
format: date-time
nullable: true
description: Time of the latest revocation; null while ACTIVE.
example: null
createdAt:
type: string
format: date-time
description: Time this worker-project grant record was first created.
example: '2026-09-14T23:00:00.000Z'
updatedAt:
type: string
format: date-time
description: >-
Feed change timestamp. Advances for access changes and changes to
embedded worker data, including fullName.
example: '2026-09-14T23:00:00.000Z'
PaginationMeta:
type: object
properties:
totalCount:
type: integer
description: How many total items there are.
example: 100
totalPages:
type: integer
description: How many pages there are based on your offset and limit.
example: 4
offset:
type: integer
description: How many items skipped before starting to collect the result set.
example: 0
limit:
type: integer
description: How many items you requested to return.
example: 25
securitySchemes:
OAuth2:
type: oauth2
flows:
clientCredentials:
tokenUrl: https://api.buildpass.global/oauth/token
scopes:
read:subcontractors: Read subcontractors
write:subcontractors: Write subcontractors
read:prequalifications: Read prequalifications
write:prequalifications: Write prequalifications
read:insurances: Read insurances
write:insurances: Write insurances
read:contacts: Read contacts
read:swms: Read SWMS
read:timesheets: Read timesheets
read:inductions: Read inductions
read:meetings: Read meetings
write:meetings: Write meetings
read:defects: Read defects
read:photos: Read photos and photo folders
write:photos: Create, update, delete, and sync photos and photo folders
read:site_access: >-
Read worker-project site access grants (planned; not yet
available)
````