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.