Sign in Subscribe

Silverfin API V4 Migration

The past half year at Silverfin we’ve been working to upgrade our infrastructure in order to handle the growth we’re experiencing in terms of data and customers, by making it possible to distribute our customers across multiple decentralised stacks while maintaining security and regulatory compliance.

As part of this change, we have to make a backwards-incompatible change to our API, in order for our load-balancers to easily be able to determine which stack an API request should be routed to. Since it’s backwards incompatible we’ve decided to release this change as a new major version of the API, namely V4, while keeping V3 around for now to give everyone time to migrate.

You can read the documentation on V4 here:

https://api.getsilverfin.com/api_docs/v4

The old documentation remains accessible here:

https://api.getsilverfin.com/api_docs/v3

The breaking change between V3 and V4 is in the URL to use, which in v4 includes a new parameter firm_id. While in V3 the URL is of the format /v3/RESOURCE, in v4 this becomes /v4/f/:firm_id/RESOURCE. In order to accommodate this new parameter firm_id, the OAuth flow has also been changed to return the firm_id of the connecting user when the user first goes through it. There are no other changes between V3 and V4.

You may have seen mentions of V4 already in the changelog mailinglist. For experiments V4 has been out for a while, and we’ve been keeping V3 and V4 in lockstep with each other. Each change in V4 also gets ported to V3 and vice versa. This means that V3 and V4 are identical except for the base URL. Right now you too can already start using V4, and for now V3 will keep working as before.

Unfortunately due to the limitations of our new infrastructure setup, we will have to remove V3 in the near future, and you will need to upgrade to V4. Since the infrastructure change roll-out happens first for new customers, there are two parts to this: existing customers and new customers.

For existing customers, meaning firms of which at least one user currently has a connection to a V3 application, we will remove V3 on August 31st, 2021. Any applications that have not been converted to use V4 by that date will stop working, but until then, existing customers using V3 applications will not notice any difference and it will keep working as before.

For new customers we will already start adding new Silverfin customers to the new infrastructure setup starting from February 2021. From that point forward, new customers will not be able to connect to V3 applications anymore, even though existing customers still can. Unfortunately we cannot give you a longer heads-up because our growth requires we move to the new infrastructure as soon as possible. If you need the ability to give new customers access to your applications, then you will need to upgrade your applications to use V4. Note that we’re merely talking about new firms here. New users of existing firms fall into the “existing customer” category and will keep working with V3 until August 31st.

In summary, existing customers will be able to use V3 applications until August 31st, 2021, but new customers will not be able to use V3 applications starting from February 2021. After August 31st, 2021 the V3 API will be completely removed and only V4 applications will function.

Required Code Changes

To start using V4, you need to make two changes to your application:

  • During the OAuth flow process, you will need to capture the firm_id of the connecting user.
  • You need to change most API calls to use the new URL format which includes this firm_id

All applications can at this time already interact with both V3 and V4 endpoints intermixed. It does not require any further action from the user, from you, or from us.

OAuth Changes

To start the OAuth process you still need to redirect the user to the same URL as before:

https://live.getsilverfin.com/oauth/authorize

After authorising, the user is redirected back to your application through a URL that includes the authorisation code. We’ve expanded this URL to now also include a URL query parameter firm_id. You need to store this firm_id because it is required to for all subsequent requests.

For example, whereas before the redirect URL was as follows:

https://localhost:3000/sf/callback?code=XXXX

Here’s the updated version that includes the firm_id:

https://localhost:3000/sf/callback?code=XXXX&firm_id=YYY

It is up to you to extract the firm_id from this URL and store it for making future V4 calls.

Code Change (URLs)

To retrieve the tokens, you now need to pass in the firm_id to the URL as follows:

https://live.getsilverfin.com/f/<firm_id>/oauth/token

The other change in V4 is that now all endpoints require the addition of /f/<firm_id>, for instance the following is an example of a v4 endpoint:

https://live.getsilverfin.com/v4/f/<firm_id>/user/firm

Migrating Existing Connections

In order to make this change as seamless as possible for existing users, you can use the following migration strategy to migrate existing OAuth connections from to start using V4 without having to force users to reconnect. Access tokens and refresh tokens used by V3 applications are also usable for V4 applications, so the only extra thing you need to do is to fetch and store the firm_id for each of the connections. Then you can start calling V4 endpoints with the tokens you already have.

Suggested steps for migrating:

  • Add a firm_id field to your local storage for API connections.
  • For each existing user connection, fetch the current firm_id using the /v3/user/firm endpoint.
  • Start using V4 endpoints together with the fetched firm_id.


Explanation


In a recent change we’ve opened up the /user/firm endpoint, which returns the firm_id of the connection, so any application can call it even if it did not acquire the correct permissions when the connection was established. You can use this endpoint to fetch the connecting user’s firm_id before migrating:

Calling GET /v3/user/firm will return a response like the following:
{
 "id": 123,
 "name": "My Firm"
}

The value “id” is the firm_id that you need.

From then on, start using that value in the V4 URLs:

GET /v4/f/123/user/firm.