Generate Token Pair

# Generate Token Pair

A token pair provides the authentication credentials required for subscribers to establish WebSocket connections to a Data Streams channel.

Before you begin, ensure you have created a channel, configured access control, and an Advanced I/O function to host the token generation endpoint.

Note: Token pair generation is a server-side operation that requires admin-level authentication. You must call getTokenPair() from a Catalyst Advanced I/O function and return the token pair to the client for WebSocket connection. Never expose token generation logic in client-side code.

A token pair contains the WebSocket server URL (url), session identifier (wss_id or zuid), authentication key (key), and channel ID (channel_id).

### Create Token Generation Endpoint

Create an Advanced I/O function that generates and returns token pairs to clients. You can generate a token pair using either User ID (for authenticated users with Catalyst Authentication) or Connection Name (for anonymous or device-based connections). You must provide at least one.

<table class="content-table">
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>channelId</td>
<td>string</td>
<td>The unique identifier of the channel to subscribe to</td>
</tr>
<tr>
<td>userId</td>
<td>string / Long (Java)</td>
<td>The Catalyst project user ID (for authenticated users)</td>
</tr>
<tr>
<td>connectionName</td>
<td>string</td>
<td>Custom connection identifier (for anonymous/device connections)</td>
</tr>
</tbody>
</table>

const { DataStreams } = require('@zcatalyst/datastreams');

module.exports = async (req, res) => {
    const datastreams = new DataStreams();
    
    // Option 1: Using a user ID (for authenticated users)
    const tokenByUser = await datastreams.getTokenPair('YOUR_CHANNEL_ID', {
        userId: 'YOUR_USER_ID'
    });
    
    // Option 2: Using a connection name (for anonymous users)
    const tokenByName = await datastreams.getTokenPair('YOUR_CHANNEL_ID', {
        connectionName: 'YOUR_CONNECTION_NAME'
    });
    
    // Return token pair to client
    res.setHeader('Content-Type', 'application/json');
    res.writeHead(200);
    res.end(JSON.stringify({ status: 'success', data: tokenByUser }));
};

import com.zc.component.datastream.ZCDatastream;
import com.zc.component.datastream.beans.ZCTokenResponse;

ZCDatastream datastream = ZCDatastream.getInstance();

// Option 1: Using a user ID (Long type for authenticated users)
Long userId = 30772000000631094L;
ZCTokenResponse tokenByUser = datastream.getTokenPair("YOUR_CHANNEL_ID", userId);

// Option 2: Using a connection name (String type for anonymous users)
ZCTokenResponse tokenByName = datastream.getTokenPair("YOUR_CHANNEL_ID", "YOUR_CONNECTION_NAME");

// Return tokenByUser or tokenByName to client

import zcatalyst_sdk

app = zcatalyst_sdk.initialize_app()
data_streams = app.datastreams()

# Option 1: Using a user ID (for authenticated users)
token_by_user = data_streams.get_token_pair("YOUR_CHANNEL_ID", user_id="YOUR_USER_ID")

# Option 2: Using a connection name (for anonymous users)
token_by_name = data_streams.get_token_pair("YOUR_CHANNEL_ID", connection_name="YOUR_CONNECTION_NAME")

# Return token to client

### Deploy and Test

To deploy and test your token generation endpoint:

1. Deploy your Advanced I/O function
2. Call the function endpoint from your client application
3. The client receives the token pair response:

{
    "url": "wss://datastreams.zoho.com",
    "wss_id": "abc123sessionid",
    "key": "authentication_key_here",
    "channel_id": "1234567890"
}

### Example Implementation

Server (Advanced I/O Function):

const { DataStreams } = require('@zcatalyst/datastreams');

module.exports = async (req, res) => {
    try {
        const datastreams = new DataStreams();
        const { channelId, userId, connectionName } = req.body;
        
        // Generate token pair
        const tokenPair = await datastreams.getTokenPair(channelId, {
            userId: userId || undefined,
            connectionName: connectionName || undefined
        });
        
        res.status(200).json({
            success: true,
            token: tokenPair
        });
    } catch (error) {
        res.status(500).json({
            success: false,
            error: error.message
        });
    }
};

Client (Request token from server):

// Client-side: Fetch token pair from your server
const response = await fetch('https://your-function-url.com/get-token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        channelId: 'YOUR_CHANNEL_ID',
        userId: 'current_user_id'  // or connectionName: 'device_123'
    })
});

const { token } = await response.json();
// Now use token to create WebSocket connection

Always validate subscriber identity before generating tokens, use User ID for authenticated users, and use Connection Name for anonymous connections. Tokens are scoped to specific channels.

You can find further steps on subscribing with WebSocket to create connections using the token pair, testing data flow to verify token generation, Token Pairs in Key Concepts, and WebSocket Connections.

A token pair provides the authentication credentials required for subscribers to establish WebSocket connections to a Data Streams channel.

Before you begin, ensure you have created a channel, configured access control, and an Advanced I/O function to host the token generation endpoint.

Note: Token pair generation is a server-side operation that requires admin-level authentication. You must call getTokenPair() from a Catalyst Advanced I/O function and return the token pair to the client for WebSocket connection. Never expose token generation logic in client-side code.

A token pair contains the WebSocket server URL (url), session identifier (wss_id or zuid), authentication key (key), and channel ID (channel_id).

Create Token Generation Endpoint

Create an Advanced I/O function that generates and returns token pairs to clients. You can generate a token pair using either User ID (for authenticated users with Catalyst Authentication) or Connection Name (for anonymous or device-based connections). You must provide at least one.

Parameter	Type	Description
channelId	string	The unique identifier of the channel to subscribe to
userId	string / Long (Java)	The Catalyst project user ID (for authenticated users)
connectionName	string	Custom connection identifier (for anonymous/device connections)

JavaScript

copy

         const { DataStreams } = require('@zcatalyst/datastreams');

module.exports = async (req, res) => {
    const datastreams = new DataStreams();
    
    // Option 1: Using a user ID (for authenticated users)
    const tokenByUser = await datastreams.getTokenPair('YOUR_CHANNEL_ID', {
        userId: 'YOUR_USER_ID'
    });
    
    // Option 2: Using a connection name (for anonymous users)
    const tokenByName = await datastreams.getTokenPair('YOUR_CHANNEL_ID', {
        connectionName: 'YOUR_CONNECTION_NAME'
    });
    
    // Return token pair to client
    res.setHeader('Content-Type', 'application/json');
    res.writeHead(200);
    res.end(JSON.stringify({ status: 'success', data: tokenByUser }));
};
    

Java

copy

         import com.zc.component.datastream.ZCDatastream;
import com.zc.component.datastream.beans.ZCTokenResponse;

ZCDatastream datastream = ZCDatastream.getInstance();

// Option 1: Using a user ID (Long type for authenticated users)
Long userId = 30772000000631094L;
ZCTokenResponse tokenByUser = datastream.getTokenPair("YOUR_CHANNEL_ID", userId);

// Option 2: Using a connection name (String type for anonymous users)
ZCTokenResponse tokenByName = datastream.getTokenPair("YOUR_CHANNEL_ID", "YOUR_CONNECTION_NAME");

// Return tokenByUser or tokenByName to client
    

Python

copy

         import zcatalyst_sdk

app = zcatalyst_sdk.initialize_app()
data_streams = app.datastreams()

# Option 1: Using a user ID (for authenticated users)
token_by_user = data_streams.get_token_pair("YOUR_CHANNEL_ID", user_id="YOUR_USER_ID")

# Option 2: Using a connection name (for anonymous users)
token_by_name = data_streams.get_token_pair("YOUR_CHANNEL_ID", connection_name="YOUR_CONNECTION_NAME")

# Return token to client
    

Deploy and Test

To deploy and test your token generation endpoint:

Deploy your Advanced I/O function
Call the function endpoint from your client application
The client receives the token pair response:

copy

         
{
    "url": "wss://datastreams.zoho.com",
    "wss_id": "abc123sessionid",
    "key": "authentication_key_here",
    "channel_id": "1234567890"
}

    

Example Implementation

Server (Advanced I/O Function):

copy


const { DataStreams } = require('@zcatalyst/datastreams');
module.exports = async (req, res) => {
try {
const datastreams = new DataStreams();
const { channelId, userId, connectionName } = req.body;
    // Generate token pair
    const tokenPair = await datastreams.getTokenPair(channelId, {
        userId: userId || undefined,
        connectionName: connectionName || undefined
    });
    
    res.status(200).json({
        success: true,
        token: tokenPair
    });
} catch (error) {
    res.status(500).json({
        success: false,
        error: error.message
    });
}

};

Client (Request token from server):

copy


// Client-side: Fetch token pair from your server
const response = await fetch('https://your-function-url.com/get-token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        channelId: 'YOUR_CHANNEL_ID',
        userId: 'current_user_id'  // or connectionName: 'device_123'
    })
});
const { token } = await response.json();
// Now use token to create WebSocket connection

Always validate subscriber identity before generating tokens, use User ID for authenticated users, and use Connection Name for anonymous connections. Tokens are scoped to specific channels.

Last Updated 2026-10-05 20:43:57 +0530 IST