Handling Auth Tokens
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:
- in a Link JS callback upon successful authentication managed authentication - recommended
- by calling /api/v1/linkToken
- by refreshing the token using the refreshToken in the following request - /api/v1/token/refresh
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
- by calling /api/v1/authenticate
- by refreshing the token using the refreshToken in the following request - /api/v1/token/refresh
- by refreshing the refresh token using the refreshToken in the following request - /api/v1/token/refresh and providing
CreateNewRefreshToken
parameter
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 emptyaccountName
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.