Authentication and Integration
Accessing the Finicity API
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.
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.
Authentication
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 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. Best practice is to use a single token for all your calls. Assign a timestamp before making any calls, and if the token is aged more than 90 minutes, a new token should be generated.
Five unsuccessful authentication attempts will cause the partner’s account to be locked. To unlock the account, send an email to support@finicity.com.
Building the URL to Call the Partner Authentication Service
To build the URL for a Finicity API, you’ll always start with the base URL: https://api.finicity.com. Then, append the specific service’s path to the base URL.
POST
/aggregation/v2/partners/authentication
Therefore, the complete URL for Partner Authentication is:
Request Headers
The Partner Authentication HTTP requests sent to the Finicity API require the following HTTP headers: Finicity-App-Key
Since this request uses POST with a JSON body, it requires an additional header: Content-Type: application/json
Finicity supports both JSON and XML.
Request Body
The Partner Authentication HTTP requests sent to the Finicity API require the following body keys and their appropriate values (from your Developer Portal dashboard):
- “partnerId”: “PARTNER_ID”,
- “partnerSecret”: “PARTNER_SECRET”
Sample Request
JSON Request:
POST https://api.finicity.com/aggregation/v2/partners/authentication
{
"partnerId": "PARTNER_ID",
"partnerSecret": "PARTNER_SECRET"
} JSON Response:
{
"token": "ACCESS_TOKEN"
} 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.
Change Finicity App Key
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.