Finicity’s partners are the corporate entities doing business with us. They create software that uses Finicity’s data aggregation or other financial web services. The following resource explains how to obtain a secure access token and change the stored partner secret.
Finicity API Security Restrictions
To access Finicity’s API, the machine connecting to the API must be located inside the United States or Canada. TLS 1.2 or higher is required for all requests to the API.
The “Partner Authentication” API endpoint is the first step in calling any Finicity API. The purpose of this call is to validate the partner’s credentials (Finicity-App-Key, Partner ID, and Partner Secret) and return a secure access token. The token must be passed in the HTTP header: “Finicity-App-Token” on all subsequent API requests.
The credentials: APP_KEY, PARTNER_ID, and PARTNER_SECRET referenced here and later in this tutorial, should be replaced with the values obtained from your Finicity developer dashboard. If you do not have a Finicity Developer account you can click here to create one.
The token is valid for two hours. Your code should call this service once every 90 minutes and then store that token to be used for all calls during that two-hour duration. Calling authentication more frequently will only create excessive and redundant traffic. You can have multiple token active at the same time.
Five unsuccessful authentication attempts will cause the partner’s account to be locked. To unlock the account, send an email firstname.lastname@example.org.
The Partner Authentication HTTP requests sent to the Finicity API require the following HTTP headers:
Since this request uses POST with a JSON body, it requires an additional header:
Finicity supports both JSON and XML, but for the purposes of this example and document, JSON is being used.
The Partner Authentication HTTP requests sent to the Finicity API require the following body keys and their appropriate values (from your Developer Portal dashboard):
Modify Partner Secret
A Partner also has the ability to change the partner secret obtained from the developer portal. The secret does not expire, and can be changed by calling “Modify Partner Secret”. Make sure the new secret follows the guidelines set for the partner secret value as documented in this article, “Modify Partner Secret”. This same article will also explain how to make the call to update the secret.
You can also rotate your Finicity-App-Key inside of the developer portal. Once you rotate your app key your old key becomes invalid so you will need to update your application configuration with the new app key immediately after rotation.
Understanding API Errors
If you receive errors while calling the API they should describe the nature of the error so it is easy to understand. However, we have documented some of the common errors that partners run into during integration. You can find those in the “Documented API Errors”.