Auth Tokens

Auth tokens provide a secure way to establish a connection between your application and Relaybox services.

Creating an Authentication Endpoint

In order to request a secure authentication token, we need to create a server-side endpoint that will respond with one. Let's go ahead and generate a token to gain access to Relaybox services.

The following example uses Express to create a simple REST endpoint that will provide an authentication token response.

// Server side
import RelayBox from '@relaybox/rest';
import express, { Request, Response } from 'express';

const relayBox = new RelayBox({
  apiKey: xxxx.xxxx.xxxxxxxxxxxx // Use API key responsibly on your server
});

app.get('/user/auth', (req: Request, res: Response) => {
  const tokenResponse = relayBox.generateTokenResponse();
  res.send(tokenResponse);
})

For more information about @relaybox/rest, and generateTokenResponse() please visit the relevant documentation

Using an Authentication Token

Now that the authentication endpoint has been created, you can reference the URL in the client-side configuration options. This can be either a relative or absolute path depending on the location of your backend services.

// Client side
import RelayBox from '@relaybox/client';

const relayBox = new RelayBox({
  authEndpoint: `/user/auth`, // Your secure authentication endpoint
})

await relayBox.connect();

By supplying the authEndpoint parameter, you're telling Relaybox that it can request a secure authentication token from this location. Once enabled, the client-side library ensures this token remains secure and valid for the entirety of the user session.

There is no more code to maintain. The client-side SDK library will securely manage refreshing the token at regular intervals and handle establishing a connection once the token response has been received.

Setting a Client ID

To allow the connecting user to participate in presence activities and operations, you can provide a client ID when generating an auth token. This could be the user ID or an arbitrary value you choose to supply.

// Server side...

// This could be a call to your db or auth service (for example)
const clientId = getClientId(); // eg. 1234

const tokenResponse = relayBox.generateTokenResponse({
  clientId
});

Once a client ID has been added to the token, this user now has an identity and will be able to participate in presence operations.

Setting the Token Expiry

Authentication tokens should be short-lived credentials. For this reason, we provide a way to set an expiry. Once the token has expired, it can no longer be used to connect to Relaybox.

// Server side...

// Set a token expiry time of 5 mins
const DEFAULT_TOKEN_EXPIRY_SECS = 300; // 5 mins

const tokenResponse = relayBox.generateTokenResponse({
  expiresIn: DEFAULT_TOKEN_EXPIRY_SECS
});

If the expiry is not specified, a default value of 15 minutes is applied. When the token is due to expire, the client-side library will initiate a request to the provided auth endpoint to get a new one.

Setting Permissions Dynamically

It's recommended that you manage token permissions at the API key level, but there will be situations where you require more control over the permissions applied to a connection. In such cases, dynamically adding permissions will be necessary.

// Server side...

// add permissions during token generation
const permissions = {
  'myRoom': ['publish', 'presence', 'metrics'],
};

const tokenResponse = relayBox.generateTokenResponse({
  permissions
});

Click here to learn more about managing permissions both programmatically and through the use of API keys.

Setting Token Request Options

Include configuration options in the token request to transmit additional data. This may include extra headers, request configurations, or other necessary information to generate the token.

// Client side
import RelayBox from '@relaybox/client';

const relayBox = new RelayBox({
  authEndpoint: `/user/auth`,

  // Alternatviely, specify a function to generate the token
  // This could be useful when working with NextJS server actions
  authAction: getRelayBoxAuthToken,

  // Attach a client id directly if required
  clientId: 1234,

  // ...or call a function to retrieve the header content
  authHeaders: function () {
    const clientId = localStorage.getItem('client-id');

    return {
      'X-Client-Id': clientId,
      'X-Refresh-Token': '...'
    };
  },

  // Javascript fetch API is used under the hood
  // Add additional config options here to be passed with the request
  authRequestOptions: {
    method: 'GET', // defaults to 'GET'
    mode: 'cors',
    credentials: 'include'
  },

  // Alternatively, pass extra parameters in the request url
  // /user/auth?clientId=...
  authParams: function () {
    const clientId = getItem('client-id');
    return {
      clientId
    };
  }
});

API Reference

Use the links below to learn more about the client and server API...

Learn more about client request options

Learn more about server response options

    On this page