Feature available for : LinkedIn, WhatsApp, Instagram, Messenger, Telegram, Google, Microsoft, IMAP, X (Twitter)

The Hosted Auth Wizard is a pre-built, optimised authentication interface that simplifies the process of connecting user accounts securely. With its built-in features, you can significantly reduce your development time and provide a streamlined authentication experience. The Hosted Auth Wizard offers support for various authentication methods, including QR code scanning, credentials-based authentication and OAuth.

Overview

📘

You can specify the 'name' parameter with your internal user ID when requesting a hosted auth link. We will return this parameter when we call your 'notify_url', in order to match the connected account with your user.

Quickstart

Step 1 : Generate a Hosted Auth Wizard link

To generate a hosted auth link, you'll need to make an API Request with the following parameters:

• Specifies whether you want to create a new connection or reconnect a disconnected account.
• Your Unipile API endpoint.
• The expiration date and time for the link in ISO 8601 format. Make sure it is a relatively short expiration period, ranging from a few minutes to a few hours.
• A list of messaging providers the user can choose from in the wizard. You can specify a specific provider or use "*" for all providers.
• Upon a user's successful login, you can configure two distinct URLs, one for success (success_redirect_url) and another for failure (failure_redirect_url), to which the user will be redirected. Additionally, you have the option to receive a webhook notification containing account-related information at a URL of your choosing (notify_url).
• You can specify the 'name' parameter with your internal user ID when requesting a hosted auth link. We will return this parameter when we call your 'notify_url', in order to match the connected account with your user

curl --request POST \
     --url https://apiXXX.unipile.com:XXX/api/v1/hosted/accounts/link \
     --header 'X-API-KEY: XXXXXXXX' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "type": "create",
  "providers": "*",
  "api_url": "https://apiXXX.unipile.com:XXX",
  "expiresOn": "2024-12-22T12:00:00.701Z"
}
'

const response = await client.account.createHostedAuthLink({
  type: "create",
  api_url: "https://{YOUR_DSN}",
  expiresOn: "2024-12-22T12:00:00.701Z",
  providers: "*",
  // More options
})

The utmost caution must be exercised to prevent the inadvertent exposure of your X-API-KEY. To accomplish this, it is necessary to establish an intermediary backend process responsible for make this api call who generate the unique link tailored to each user.

Upon a user's successful login, you can configure two distinct URLs, one for success (success_redirect_url) and another for failure (failure_redirect_url), to which the user will be redirected. Additionally, you have the option to receive a webhook notification containing account-related information at a URL of your choosing (notify_url).

Step 2 : Receive the Hosted Auth Link

Upon a successful API request, you'll receive a response containing a hosted auth URL. This URL is the link that will guide users through the authentication process.

{
  "object": "HostedAuthURL",
  "url": "https://account.unipile.com/pqb%2Gz77l.o72WXNPdqWX45jxqP5xMMlQp02zho8GAXZq0HWsAGiQ%3D"
}

Step 3: Implement the Hosted Auth Link

We strongly recommend the implementation of an automatic redirection mechanism when a user clicks a 'connect account' button within your application.

Reconnecting an account with Hosted Auth Wizard

The reconnection link follows a similar path as the initial connection process, but with the type parameter set to reconnect, and it necessitates the inclusion of the account ID (reconnect_account).

Example usage

1. First, you need to set up a webhook to monitor account status updates. Specifically, you should look for the "CREDENTIALS" status change, which indicates that an account requires reconnection.
2. Upon detecting the "CREDENTIALS" status update, send an email to the user. In this email, provide a link that will allow them to initiate the reconnection process. Ensure that the email contains clear instructions and reassures the user about the security of the process.
3. When the user clicks on the reconnection link in the email, they should be directed to your backend service. This backend service generates a hosted Auth Wizard link using the Unipile API
4. After generating the hosted Auth Wizard link, redirect the user to this link. The user will follow the authentication steps to reconnect their account securely.

Custom Domain URL (White-label)

You can establish a CNAME using your own URL (e.g., auth.yourapp.com) pointing to account.unipile.com.

Once set up, please contact us for authorization. Following approval, you can update the URL in your code to replace any visible mentions of Unipile with your custom domain.