Scopes and subsidiary access
API Documentation / Authorization
Scopes limit what an access token can do. Subsidiary grants limit where it can do it. Both checks apply to every request.
The effective scopes are the intersection of:
- Scopes declared on the application registration.
- Scopes requested in the authorization request.
- Scopes approved by the authorizing user.
- Scopes currently allowed by Finovio for that subsidiary grant.
Available scopes
| Scope | Access |
|---|---|
accounting:read |
Read core accounting reference data, accounts, taxes, payment terms, currencies, and posted journals. |
accounting:write |
Create and maintain accounts, taxes, and payment terms. |
contacts:read |
Read customers, suppliers, contacts, and related addresses. |
contacts:write |
Create, update, archive, and restore contacts. |
dimensions:read |
Read dimensions and dimension elements. |
dimensions:write |
Create, update, and archive dimensions and dimension elements. |
fixedassets:read |
Read fixed-asset types, assets, events, and attachments. |
fixedassets:write |
Maintain fixed-asset types and assets and perform supported asset lifecycle actions. |
invoices:read |
Read sales invoices, bills, credit notes, and their status. |
invoices:write |
Create and update supported invoice records. Read access must also be requested when the integration needs to retrieve them. |
manualjournals:read |
Read manual-journal drafts and their posted journal details. |
manualjournals:write |
Create, update, post, and otherwise act on supported manual journals. Read access must also be requested when the integration needs to retrieve them. |
bankbatches:write |
Submit API-sourced bank transaction batches and delete eligible API batches. This scope does not grant reconciliation access. |
payroll:read |
Read payroll settings, employees, leave, pay runs, payslips, and payment files allowed by the authorizing user's payroll capabilities. Payroll mutations are never available through v1. |
reports:read |
Run supported financial reports and retrieve report drill-down data. |
Request only the scopes required for the integration's current features. Adding requested scopes to an application does not update existing grants. Users must authorize the additional scopes.
Subsidiary-bound tokens
Each token pair is bound to one tenancy and one subsidiary. Both UUIDs are returned by the token endpoint and must match the request path.
Using a valid token with another tenancy or subsidiary returns 403 Forbidden. It does not reveal whether the other resource exists.
An application that works with several subsidiaries must complete authorization separately for each one and keep each token pair associated with its returned context.
User and application changes
Authorization depends on both the user's authority and the application's status. A grant may stop working when the authorizing user's access is removed, the subsidiary grant is revoked, the application is revoked or deleted, or a Finovio administrator changes its allowed scopes.