finov.ioDocumentationHome

Build your first integration

API Documentation / Getting Started

This flow describes the intended path from application registration to an authenticated API request.

1. Register an application

Open Developer Tools in Finovio and create an application. Provide its name, homepage, privacy policy, terms of use, redirect URIs, and requested scopes.

Finovio displays a client_id and a client secret when the application is created. Store the secret in a secret manager. It is not shown again. Do not embed it in browser or mobile code.

The first API release supports confidential web-server applications. The browser receives only the client ID, authorization request, and callback code. Your trusted server submits the client secret directly to the token endpoint over TLS. Finovio never asks the user to enter your client secret.

Redirect URIs must be absolute HTTPS URLs in production. The URI supplied during authorization and token exchange must exactly match a registered value.

2. Send the user to authorize

Generate a fresh state, PKCE code_verifier, and S256 code_challenge for each attempt. Redirect the user to:

https://api.finov.io/oauth/authorize
  ?response_type=code
  &client_id={client_id}
  &redirect_uri={url_encoded_redirect_uri}
  &scope=invoices%3Aread%20contacts%3Aread
  &state={state}
  &code_challenge={code_challenge}
  &code_challenge_method=S256

The user signs in, selects one tenancy and subsidiary, and approves scopes. Finovio then redirects to the registered URI with a short-lived, single-use code:

https://app.example.com/oauth/callback?code={authorization_code}&state={state}

Reject the callback if state does not match the value stored for the authorization attempt.

3. Exchange the code

Send the code from your server. Authenticate the client with HTTP Basic authentication using the client ID as the username and client secret as the password.

{base64_client_id_and_secret} means Base64 encoding the UTF-8 string {client_id}:{client_secret}. Base64 is not encryption, so the request must use HTTPS and the value must not be logged.

POST /oauth/token HTTP/1.1
Host: api.finov.io
Authorization: Basic {base64_client_id_and_secret}
Content-Type: application/x-www-form-urlencoded
Accept: application/json

grant_type=authorization_code&code={authorization_code}&redirect_uri={url_encoded_redirect_uri}&code_verifier={code_verifier}

A successful exchange returns a bearer token, rotating refresh token, and the grant context:

{
  "access_token": "{access_token}",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "{refresh_token}",
  "scope": "contacts:read invoices:read",
  "tenant_id": "07224707-2351-46b4-a810-5fee961b5823",
  "subsidiary_id": "84224707-2351-46b4-a810-5fee961b6373"
}

The example lifetime is illustrative. Clients must use the returned expires_in value rather than assuming a fixed lifetime.

4. Call the API

Use the returned tenancy and subsidiary identifiers in the path and send the access token as a bearer token:

GET /v1/tenants/07224707-2351-46b4-a810-5fee961b5823/subsidiaries/84224707-2351-46b4-a810-5fee961b6373/invoices?per_page=30 HTTP/1.1
Host: api.finov.io
Authorization: Bearer {access_token}
Accept: application/json

Continue with OAuth authorization for refresh and revocation behavior.