finov.ioDocumentationHome

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:

  1. Scopes declared on the application registration.
  2. Scopes requested in the authorization request.
  3. Scopes approved by the authorizing user.
  4. 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.