Subsidiary-scoped API credentials
API credentials can now be scoped to specific subsidiaries. A scoped credential's access token is limited to the data of the subsidiaries it was issued for — across every read and write endpoint of the Public API, including webhooks.
What changed
Previously, every API credential had tenant-wide access: any token could read and modify data belonging to any subsidiary in your company. Subsidiary selections made during credential creation were stored but not enforced.
Now, when a credential is created with one or more subsidiaries selected, that scope is embedded in the access token and enforced on every request.
How token scope works
When you request an access token, Alvys adds a new claim to the token:
https://alvys.com/claims/app/subsidiariesThe claim is added automatically when the token is issued and restricts the credential's access to only the subsidiaries it has been granted. It is evaluated on every API request, with no additional configuration required.
Scope rules:
| Your credential setup | Claim in the token | What the token can do |
|---|---|---|
| Scoped to specific subsidiaries (up to 3) | The subsidiaries' IDs | Only see and edit those subsidiaries' data |
| All subsidiaries selected | * | Access every subsidiary in your company |
| No subsidiaries selected | * | Access every subsidiary in your company |
| Credentials created before this release | * | No change — same access as before |
What a scoped token can see and do
Reads — search and list endpoints return only records belonging to the credential's subsidiaries, plus records that have no subsidiary assignment (tenant-level data). Get-by-ID requests for a record outside the scope return 404 Not Found, exactly as if the record did not exist.
Writes — a scoped token cannot create, update, or delete records outside its subsidiaries. Out-of-scope writes return 404 Not Found — the same response as a nonexistent record, so a scoped credential cannot probe for the existence of another subsidiary's data. This covers load updates, notes and documents, trip assignment/dispatch, stop arrivals/departures/appointments, check calls, customer updates and deletes, deductions, invoice payments and financing, and asset document uploads.
Webhooks — webhook subscriptions are subsidiary-bound. A scoped credential can only create, list, manage, and read delivery logs for webhooks belonging to its own subsidiaries, and can only subscribe to events of those subsidiaries.
Scoped entities
Subsidiary scope applies to: Loads, Trips (including stops and check calls), Invoices, Customers, Deductions, Fuel transactions, Tolls, Drivers, Trucks, Trailers, Driver Settlement Statements, Carrier Settlement Statements, and Webhooks. Carriers and Tenders are not subsidiary-scoped.
Response code changes
One response code changed as part of this work: POST /api/p/v{version}/trips/{tripId}/assign with an unknown trip ID now returns 404 Not Found (previously 400 Bad Request). This aligns assign with the other trip endpoints and is required for the no-existence-leak guarantee above. No other status codes changed.
Backward compatibility
Existing credentials and integrations are unaffected. Tokens issued from credentials without a subsidiary selection — including all credentials created before this release — remain tenant-wide. Scoping only applies when you explicitly select subsidiaries on a credential.
Creating a scoped credential
- Navigate to Settings → API Keys
- Click New credential
- Select permissions and choose the subsidiaries the credential may access — up to 3 specific subsidiaries, or All subsidiaries for tenant-wide access
- Click Generate and store the Client ID and Secret securely
Tokens requested with these credentials via the standard OAuth 2.0 Client Credentials flow will carry the subsidiary scope automatically.