How to Associate a Connection ID with Your End-User

November 12, 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:

Before you begin

This guide assumes you have:

• A basic understanding of 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:
   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:
   const encodedState = Buffer.from(JSON.stringify(stateObject)).toString('base64');
   

3. Add the encoded state to your authorization URL
   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:
   // 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
   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:
   
   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