Chat with us on Discord
Unified.to
Case study: How Humi saved $1m in engineering costs with Unified.to
Blog

How to Associate a Connection ID with Your End-User

April 4, 2024

TL;DR

This article explains three ways to associate the ID of an end-user in your application with the ID of that end-user's connection to an integration in Unified.to:

  1. Use the state parameter. Encode the end-user's ID in the state parameter of the authorization page URL; decode the end-user's ID from the state parameter and get the connection ID from the id parameter of the Success URL. We recommend this method.
  2. Use the External ID (uid) parameter. Put the end-user's ID in the External ID parameter of the authorization page URL. The user ID will be associated with the connection ID in our database, which you can query with our Connection API.
  3. Use the session cookie and the id parameter. Associate the end-user's ID (which you know from the session cookie) with the connection ID (the id parameter in the Success URL).

You may find it helpful to read this article first: Users, Integrations, and Connections__.

This method ensures that your application receives both the end-user's ID and the ID of that end-user's connection from a single source: the parameters of the Success URL.

The state parameter is included in both these URLs:

  1. The authorization URL, which redirects the end-user to the service page where they enter their credentials to authorize Unified's connection to the service.
  2. The Success URL, which redirects the end-user back to your application after they successfully authorize the connection.

The state parameter does not change during authorization. Whatever value your application puts into the state parameter in the authorization URL is the same value that it will extract from the state parameter in the Success URL.

Before authorization: Put the end-user's ID into the authorization URL's state parameter

Your application should encode the end-user's ID into the state parameter of the authorization URL. You can set state to any value that can be expressed as an URL-friendly string, including JSON objects such as this one…

`{"user_id": "xyz789"}`

…would look like this as a base64-encoded string:

`?state=eyJ1c2VyX2lkIjogInh5ejc4OSJ9`

We strongly recommend that you add some sort of security like a hashing signature into the value you put into state and then use base64 encoding on the encrypted value. Here's an example:

`{"user_id": "zyx789", nonce: "12345", "sig":"ad04e0f0f91bc51b0a0352"}`

Here's what it would look like as a base64-encoded string:

`?state=eyJ1c2VyX2lkIjogInp5eDc4OSIsIG5vbmNlOiAiMTIzNDUiLCAic2lnIjoiYWQwNGUwZjBmOTFiYzUxYjBhMDM1MiJ9`

After authorization: Get the end-user's ID and connection ID from the state and id parameters of the Success URL

Your application should decode the end-user's ID from the Success URL's state parameter and the connection ID from the id parameter. It should then store the connection ID and associate it with the end-user.

Method 2: Use the External ID (uid) parameter

With this method, your application doesn't need to record which connection IDs are associated with a user. Instead, it relies on Unified.to to do this.

The Success URL has another parameter, uid, also known as the External ID parameter, which normally means your end-user ID (be it a user or account ID).

Once a connection is created, that External ID is stored in the connection object. You'll be able to query Unified.to's Connection API using your application's user IDs to get the IDs of that user's connections.

This method relies on your application "knowing" the ID of the current end-user, thanks to the browser's session cookie.

Unlike the methods listed above, your application doesn't have to set the values for any parameters of the authorization URL. Instead, it gets the connection ID from the Success URL's id parameter (as usual) and associates it with the end-user's ID, which it should be able to get from the session cookie.

Summary

Here are the ways you can associate a connection ID with an end-user ID, listed in order of most to least recommended:

  1. Using the state parameter in the authorization and Success URLs.
  2. Using the External ID (uid) in the authorization URL.
  3. Using the session cookie + the id parameter in the Success URL.
Blog