This guide explains the integration tokens system within Mesh API, encompassing the processes of token generation, renewal, and storage. It can be used to better understand the system so that developers can follow best practices when integrating with Mesh APIs.

​
What is a “token”

AccessToken or AuthToken is a generated secret (sequence of symbols) that is returned by Mesh API upon successful account authentication and used in subsequent requests to access the user’s data.

Each token represents a connection between a particular user (typically, an end user of a client) and the user’s brokerage/exchange/wallet account.

The token grants access to the user’s data and enables the execution of read and (based on the integration) write operations. Therefore, it is essential to store the token with utmost security measures in place.

​
Types of tokens

There are 2 types of tokens provided by the Mesh API:

​
AccessToken

A token that allows performing read and write operations with the connected account.

Can be obtained in the following ways:

​
RefreshToken

A token that is returned by some integrations and needs to be used to refresh the access token before it expires.

Provided typically by OAuth and username password integrations, it is critical that it is handled correctly in order to ensure continued connections to accounts.

Can be obtained in the following ways:

— in a Link JS callback upon successful authentication managed authentication - recommended

​
Walkthrough

​
Step 1: Get tokens

You can use the SDK callback function onIntegrationConnected() to capture the accessTokenPayload after the user successfully connects an account. In particular, the elements you’ll need are:

  • accessToken
  • refreshToken
  • expiresInSeconds
  • refreshTokenExpiresInSeconds
  • brokerType
  • brokerName

​
Step 2: Associate tokens with a user

You can use any unique identifier you have to associate this with one user.
This step is very important to ensure you don’t load one user’s account for a different user.

​
Step 3: Store tokens securely

Store tokens in a secure and encrypted storage layer such as a key management system.

​
Step 4: Add in logic to refresh tokens as necessary

Check if expiresInSeconds value is present. If so, it means that the accessToken should be refreshed before it expires.
Create logic that registers the timestamp when the accessToken is obtained, records the expiresInSeconds, and uses the refreshToken in a POST to the endpoint /api/v1/token/refresh before timestamp + expiresInSeconds occurs.
If refreshTokenExpiresInSeconds is also provided, create the same logic for the refreshToken to refresh it with a call to the same endpoint with CreateNewRefreshToken: true parameter before timestamp +refreshTokenExpiresInSeconds occurs.

Note: it is a bad practice to rely on 401 responses to update tokens after they have expired.

​
Step 5: Pass this data when initializing the Mesh SDK for a specific user

Method to load SDK: createLink()…
Within the IntegrationAccessToken interface…
Pass the following for the object accessTokens…

  • accessToken
  • brokerType
  • brokerName
  • accountId can be empty
  • accountName can be empty

This can be an array (ie. different access tokens for each integration that the user has previously linked).

​
A note on UX considerations for implementation

If you would like the user to go directly to a specific integration when launching Mesh’s SDK (for example if you have a “Deposit from Coinbase” button in your UX), then you can additionally include an integrationId in the linkToken request. This will skip the catalog and would normally bring the user to that integrations authentication flow. But if an accessToken is supplied for this integration when initializing the SDK, then the user will go right into the transfer flow when Link launches (ie. they will skip catalog and skip auth).

If you would like the user to see the catalog (ie. maybe there’s a general “Deposit directly from your exchange or wallet” button in your UX), then you can simply follow the steps above to pass any accessTokens available for the user (one or an array). If the user selects an integration from the catalog for which there is an available accessToken, they will skip auth and go right to transfer.