---
title: "How to Associate a Connection ID with Your End-User"
img: https://s3.us-east-2.amazonaws.com/unified-article-images/how_to_associate_a_connection_id_with_your_end_user-icon.png
date: 2024-04-04T00:00:00.000Z
tag: Guides
description: "This guide explains how to associate connections you create through Unified.to with end-users in your own application."
url: "https://docs.unified.to/guides/how_to_associate_a_connection_id_with_your_end_user"
---

# How to Associate a Connection ID with Your End-User
------
_April 4, 2024_

This guide explains how to associate connections you create through Unified.to with end-users in your own application.


When your end-users authorize access to third-party applications through Unified.to, you need a way to keep track of which connections belong to which users in your application. This guide covers two ways to accomplish this, with recommendations on when to use each approach. 


If you prefer to learn through video, check out our guide on YouTube:


<iframe width="560" height="315" src="https://www.youtube.com/embed/OW-1vE04cFw?si=EGXIESpEGgYSq0j8" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>


## Before you begin


This guide assumes you have:

- A basic understanding of [end-users, integrations, and connections](https://unified.to/blog/end_users_integrations_and_connections)
- Familiarity with OAuth 2.0 authorization flows

## Method 1: Use the state parameter (recommended)


The state parameter provides a secure way to maintain context throughout the OAuth flow by passing data between your authorization request and the callback. The state parameter _does not_ change during authorization. Whatever value you put into the state parameter in the authorization URL is the same value that will be extracted from the success URL.

1. Create a state object with your user's ID, passing in additional security measures like a hashing signature. For example:

    ```javascript
    const stateObject = {
      user_id: "xyz789",
      nonce: generateRandomString(), // Add randomness for security
      timestamp: Date.now(), // Optional: Add timestamp for expiry checking
      sig: generateSignature() // Optional: Add signature for verification
    };
    ```

2. Encode the state object as a base64-string:

    ```javascript
    const encodedState = Buffer.from(JSON.stringify(stateObject)).toString('base64');
    ```

3. Add the encoded state to your authorization URL

    ```javascript
    const authUrl = `https://api.unified.to/unified/integration/auth/${workspace_id}/${integration}?state=${encodedState}`;
    ```

4. Handle the callback after successful authorization. The connection ID is included in the URL as `id`. For example:

    ```javascript
    // In your callback handler
    function handleCallback(req, res) {
    // Get connection ID from the callback URL
      const connectionId = req.query.id;
    
    // Decode and verify the state
      const decodedState = JSON.parse(Buffer.from(req.query.state, 'base64').toString());
    
    // Verify the state is valid (check signature, nonce, timestamp if used)
      if (verifyState(decodedState)) {
    // Associate the connection ID with the user ID in your database
        await saveUserConnection(decodedState.user_id, connectionId);
      }
    }
    ```


## Method 2: Use the external ID parameter


This method leverages Unified.to's built-in external ID (`uid`) field to store your user associations. The success URL contains another parameter, `uid`, also known as the **External ID** parameter, which can be used to map to your end-user's ID.

1. Add the external ID parameter to your authorization URL

    ```javascript
    const authUrl = `https://api.unified.to/unified/integration/auth/${workspace_id}/${integration}?uid=${user_id}`;
    ```

2. Once a connection is created, that external ID is stored in the connection object. You can now query connections using the external ID:

    ```javascript
    const options = {
      method: 'GET',
      url: 'https://api.unified.to/unified/connection',
      headers: {
        'authorization': `Bearer ${unified_api_key}`
      },
      params: {
        external_xref: user_id
      }
    };
    ```


## Best practices for implementation

1. **Always validate the state parameter**
    - Check signatures if used
    - Verify nonces haven't been reused
2. **Securely store connection associations**
    - Use a database to map user IDs to connection IDs
    - Consider encrypting sensitive data
3. **Handle error cases**
    - Missing parameters
    - Failed authorization attempts