​

Authenticating Accounts via Link

This guide details the various methods for authenticating users with Link, enabling secure connections to their external accounts. We will cover basic user identification and advanced routing for streamlined integration experiences.

​

Basic User Identification via UserId

The fundamental approach to initiating a Link flow involves simply providing the UserId. This method allows the user to navigate the full Link integration catalog.

Request Body:

{
  "UserId": "unique_end_user_identifier"
}

• UserId: A string representing the unique identifier for the end user within your application.

​

Direct Integration Launch via IntegrationId

For optimized user flows targeting specific platforms, Link supports direct launch into a designated integration (e.g., Binance, Coinbase). This bypasses the full integration catalog, improving user experience for focused connection scenarios.

Implementation:

1. Retrieve IntegrationId: Obtain the unique identifier for the target integration by querying the Retrieve the list of all available integrations endpoint. The id field within the integration object represents the IntegrationId.

2. Include IntegrationId in Link Token Request:

   {
     "UserId": "unique_end_user_identifier",
     "IntegrationId": "specific_integration_uuid"
   }
   

   • IntegrationId: The uuid of the target integration.

​

Direct Self-Custody Wallet Launch via IntegrationId

Similar to direct exchange/brokerage launch, you can route users directly to the connection flow for a specific self-custody wallet (e.g., MetaMask) using the IntegrationId.

Implementation:

The process mirrors direct exchange/brokerage launch:

1. Retrieve IntegrationId: Utilize the “Retrieve the list of all available integrations” endpoint to identify the id of the desired self-custody wallet integration.

2. Include IntegrationId in Link Token Request:

   {
     "UserId": "unique_end_user_identifier",
     "IntegrationId": "specific_wallet_integration_uuid"
   }
   

   • IntegrationId: The uuid of the target self-custody wallet integration.

​

Enforcing Single Account Connection via RestrictMultipleAccounts

By default, Link allows users to connect multiple provider accounts within a single session. To enforce a single account connection, the RestrictMultipleAccounts parameter can be set to true.

Implementation:

{
  "UserId": "unique_end_user_identifier",
  "RestrictMultipleAccounts": true
}

• RestrictMultipleAccounts: A boolean flag. When set to true, the Link UI will prevent the user from connecting additional provider accounts after a successful connection.

​

Request Structure

All the above configurations are passed within the JSON body of a POST request to the /api/v1/linktoken endpoint. Ensure that your X-Client-Id and X-Client-Secret are correctly included in the request headers for API authentication.