Guide to Partner Authentication and Integration

Partners

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.

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.

Partner 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 (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 to support@finicity.com.

Technical Articles

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. 

Partner Authentication URL:

The path for the service Partner Authentication is:

/aggregation/v2/partners/authentication

Therefore, the complete URL for Partner Authentication is:

https://api.finicity.com/aggregation/v2/partners/authentication

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

Note:

Finicity supports both JSON and XML, but for the purposes of this example and document, JSON is being used.

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.

Technical Articles

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. You can find those in the “Documented API Errors”.

Technical Articles