Authorization and Scopes
A request must satisfy the endpoint's scope requirement and the API key's company or agency access restrictions. Some operations also require permissions held by the user who created the key.
How access is evaluated
- Credentials: the key must be valid for the environment, unexpired, unrevoked and allowed from the caller's IP.
- Resource scope: the key must include the read or write scope required by the endpoint.
- Data access: the requested record must belong to the companies or agencies available to the key.
- Operation rules: endpoint-specific permissions, feature requirements and record-state restrictions must also be satisfied.
A scope is not a grant of unrestricted access to a resource. For example, read:invoices on an agency key returns only invoices available to that agency. Adding a company filter narrows permitted results; it cannot grant access to another company.
Company and agency keys
| Key type | Access boundary |
|---|---|
| Company-scoped | One or more hiring companies attached to the key, subject to the endpoint's record and permission checks |
| Agency-scoped | One or more agencies attached to the key, restricted to their permitted records for connected companies |
When a supported company filter is omitted, list endpoints use the companies available to the key. An agency key remains restricted to its agencies even when querying a connected company's data.
Agency availability varies by endpoint. Check the Agency-scoped keys warning and caller-specific parameter sections on the endpoint reference; a scope listed below does not imply that every endpoint in that resource area is available to both key types.
Available Scopes
Scopes are grouped by resource area. Related read and write scopes are listed together. Company keys are used by hirers; agency keys are used by agencies.
Companies and users
| Scope | Company keys | Agency keys | Covers |
|---|---|---|---|
read:companies | Yes | Yes | Company list and competency matrix; company keys also cover company detail, configuration, regions, sectors, connected agencies and umbrellas |
read:users | Yes | Yes | List users visible to the key owner; company assignment and permission reports remain company-only |
write:users | Yes | Yes | Create users and update profiles or memberships for hirer users with company keys, or agency users with agency keys; key-owner permissions also apply |
Projects and sites
| Scope | Company keys | Agency keys | Covers |
|---|---|---|---|
read:projects | Yes | No | Projects, cost codes and project connected agencies |
read:sites | Yes | Yes | Site list for company keys; site detail for both key types where permitted |
Workforce and recruitment
| Scope | Company keys | Agency keys | Covers |
|---|---|---|---|
read:workers | Yes | Yes | Workers and worker document detail |
write:workers | Yes | Yes | Agency keys can create and update workers; company keys can validate worker attachment and right-to-work documents |
read:requisitions | Yes | Yes | Requisitions |
read:assignments | Yes | Yes | Assignments |
read:trades | Yes | Yes | Trade list for company keys; trade detail for both key types |
read:rates | Yes | Yes | Standalone rates |
Timesheets and finance
| Scope | Company keys | Agency keys | Covers |
|---|---|---|---|
read:timesheets | Yes | Yes | Timesheets and expenses |
read:invoices | Yes | Yes | Invoices, AfP and payment notices |
write:invoices | Yes | Yes | Update invoice status; agency keys require the hiring company’s Update invoice status agency action |
read:purchase-orders | Yes | No | Purchase orders |
write:purchase-orders | Yes | No | Create, amend, revoke and reinstate purchase orders |
read:credit-notes | Yes | Yes | Credit notes |
Choose scopes for an integration
Start with the read scopes needed for the datasets you will use. Add write scopes only for explicit workflows, and confirm that the key type and key owner can perform those actions. A write scope does not include the corresponding read scope automatically.
User listing requires read:users; read:companies alone does not grant it. Agency keys can list permitted agency users, while company assignment and permission reports remain company-only.
Some utility endpoints have different requirements. API Key Info requires a valid key without an additional resource scope. List Access Rule Mappings requires company-scoped access without a resource scope. Create File Upload requires the write scope and access appropriate to the selected resource.
Diagnose an access failure
A missing scope or a disallowed operation returns 403 FORBIDDEN. A record outside the caller's data access may return 404 NOT_FOUND, so a valid ID does not guarantee a successful lookup.
Use API Key Info to inspect the key's scopes and company or agency assignments. If access is insufficient, ask the key administrator to review the integration's requirements rather than broadening scopes by default. See Responses and Errors for other failure conditions.