OAuth Connections

One of the driving factors for moving from the legacy connection to an OAuth connection is the ability to authorize and authenticate accounts using access tokens. This eliminates the need for the FI or Finicity from having to pass or store usernames or passwords when sending or receiving account information as they do now on the standard (Legacy) connection.

Other benefits include:

  • Increases the connection speed to access and retrieve more real-time consumer data.

  • Improved security accessing Finicity’s APIs as you develop your own applications.

  • Customers can manage their own accounts, giving Finicity permission to access only the accounts they want to share.

  • Customers can disconnect from the FI at any time.

  • Customers can easily access their accounts in your application even when they change their sign-on credentials.


    Example    : Currently, if a user changes the username or password on their account, they have to update their credentials in your application. If the FI was using an OAuth connection and the user changed their credentials, they’d still have access to their accounts in your application as long as the access token was valid.

Migrate to OAuth Overview

Migrating to an OAuth connection is a process that you’ll follow every time Finicity announces a new FI contract with an OAuth connection is available for you to access.

The impact to your customers is that when their account moves from the FI’s legacy connection to the new OAuth connection, they’ll have to sign-on and re-authenticate their account using an OAuth access token.

You can also expect the following:

  • We’ll work with you throughout each migration milestone.

  • Coordinating our efforts with yours to transition your customers from the old to the new OAuth connection.

  • We’ll match data from the old to the new connection without duplicating or missing any of your data.

Notify Your Customers

When it starts getting closer for OAuth going live, we’ll send you approved messages for you to pass on to your customers. There are many media outlets you can use to keep customers updated when they should expect to re-authenticate their accounts.

Notification options include:

  • Your websites

  • Login screens

  • In your mobile application on the Add Account or Refresh Account screens

  • The screen before Finicity Connect starts from your mobile application

  • Broadcast Emails

The migration process

  • 1.

    Register applications with Finicity.

  • 2.

    A new FI contract with an OAuth connection is announced.


    Note:     You only have to register your applications with Finicity one time. All future new FI’s announced with OAuth connections, you can skip this step, but you’ll still have to follow the rest of the migration process.

  • 3.

    Launch date—We’ll let you know when the new OAuth connection is active.

  • 4.

    Migrate customer accounts.

  • 5.

    Legacy connection retires.

Register Your Applications

You must register each of your applications with Finicity so that customers can identify your application name and logo in the process flow of Finicity Connect. The permissions that a customer gives to an account for access are also specific to your application and to the specific FI.

After your apps are registered, then we register your applications with current FI’s, all current OAuth FI’s, and any future FI’s as they become available. Since some FI’s take longer than others to register, we recommend that you start registering your applications as soon as possible.

Any partner who would like help registering your apps can reach out to their Finicity account representative.

Register Application APIs

Use our APIs to register one or more apps, modify your registration, or check on the status of the registration.

App Registration API

  •  Used to register new applications with Finicity to access FI’s with OAuth connections. See Register App API.

Modify App Registration API

Get App Registration Status v2 API

Multiple Applications

Use the following APIs to assign an application ID to each of your customers. This lets Finicity know which customers have permission to use your applications.

 Add Customer v2 API

  • Used to map the customer you create to the application ID. See Add Customer API.

 Set Customer Application ID API

  • Used for existing customers to set their customer ID and application ID to map the application. See Set Customer App ID API.

Important: You must assign an application ID to all existing customers, or they’ll fail to aggregate successfully.

Migrate Customers

After you start using the OAuth connection, the legacy connection is still available for 90 days so that you can migrate your customers from the old to new connection. You can choose how you want to migrate existing customers, and how you want to manage new account customers.

Migrate existing customer options:

  • 1.

    Manage to move your customer accounts however you want using the Migrate Institution Login Accounts API.

  • 2.

    Wait for the 90 days to end at which time, any accounts remaining on the legacy connection will automatically migrate to the OAuth connection.

Regardless of how you manage to migrate your accounts, if there are any remaining customer accounts on the legacy connection after 90 days, then Finicity will automatically move them to the new OAuth connection for you.

New customers and OAuth:

  • 1.

    You can decide if you want new customer accounts to start using the OAuth connection right away. See Institution Settings.

  • 2.

    Or, you can continue using the legacy connection through the 90-day period after which, we’ll automatically replace legacy with the OAuth connection.

Migration Service

The Migrate Institution Login Accounts API is used to automatically change information that’s needed to move customer accounts from an FI’s legacy connection to an OAuth connection. The migration service does three things:

  • 1.

    It changes the FI ID from the legacy connection and updates the FI ID for the OAuth connection.

  • 2.

    After the FI ID is updated, we then put the aggregation status code of the account to code 948. This code is used to programmatically display specific messages to the customer about authenticating their accounts for the first time.

  • 3.

    The financial institution transaction identifier is formatted to assure deduplicating transactions. Now that the account is placed in a 948 aggregation status, you can use the status as a programmed indicator to prompt the customer to authenticate their account using the new OAuth method.

Your applications need to do the following:

  • 1.

    Indicate to the customer that their FI has updated their connection, which requires them to sign-on to their account to reauthenticate on the new connection.

  • 2.

    Make a call to the Generate Fix Connect URL API for the institutionLoginId account set.

  • 3.

    Present Connect Fix flow to the customer.

Legacy connection retires

The legacy connection retires after the 90-day time period expires.