finov.ioDocumentationHome

API overview

API Documentation / Getting Started

Finovio provides developer tools and a JSON API for approved accounting integrations. Applications connect only to subsidiaries and capabilities explicitly approved by an authorized Finovio user.

Platform model

Finovio workspace switcher listing available company groups and subsidiary counts
The first step lists the company groups available to your account.

Finovio separates centralized identity and access management from subsidiary accounting records. Users sign in through the common access layer, while accounting services own the ledgers, contacts, invoices, bank activity, journals, fixed assets, and reports for their assigned tenants.

Every accounting request is scoped to both a tenancy and a subsidiary. The tenancy represents the company group. The subsidiary owns its accounting records, base currency, chart of accounts, contacts, invoices, journals, fixed assets, and reporting context.

The proposed public API uses this base path:

https://api.finov.io/v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}

Identifiers are UUIDs. Clients must treat them as opaque, case-insensitive strings and must not infer relationships from them.

Authorization model

Developers register a confidential application and declare the scopes it needs. An authorized group user then approves one subsidiary and a subset of those scopes through OAuth 2.1 Authorization Code with PKCE.

An application may hold grants for several subsidiaries, but each access-token and refresh-token pair is bound to one tenancy, one subsidiary, and one approved scope set. Repeat authorization for each additional subsidiary. Application registration by itself provides no access to accounting data.

Contract principles

  • Least privilege: a token cannot exceed the application's requested scopes or the user's approved scopes.
  • Explicit context: the tenancy and subsidiary in the request path must match the token grant.
  • Stable identifiers: relationships use UUID identifiers rather than names or database IDs.
  • Predictable JSON: successful JSON responses and errors use documented media types and structures.
  • Safe evolution: breaking changes require a new major API version.

Availability model

New applications begin in Developer Mode. They may only be authorized for tenancies to which the developer already belongs. Developer Mode grants begin at 30 requests per subsidiary per minute. Published applications begin at 120 requests per subsidiary per minute unless Finovio assigns a different limit.

Next steps

Register an application in Developer Tools, then follow Build your first integration. Before implementing authorization, read Scopes and subsidiary access.