@relaybox/rest

The purpose of this library is to enable seamless integration between your server-side applications and RelayBox's REST services.

Installation

To install the REST SDK library, be sure to install npm your machine if you havn't already, then simply run:

npm install @relaybox/rest

Once you have successfully installed the library, see below for the complete API reference.

RelayBox Class

First up, you'll need to initiate a new RelayBox instance with your API key.

const relayBox = new RelayBox();

class RelayBox {
  constructor(opts: RelayBoxOptions);
  generateTokenResponse(params: TokenResponseParams): TokenResponse;
  publish(roomId: string | string[], event: string, data: any): Promise<PublishResponseData>;
}

RelayBoxOptions

RelayBox class constructor options:

interface RelayBoxOptions {
  apiKey?: string;
  region: string;
}

interface TokenResponseParams {
  clientId?: string | string[];
  expiresIn?: number;
  permissions?: Permission[] | Permissions;
}

interface TokenResponse {
    token: string;
    expiresIn: number;
}

const allowedPermissions: readonly [
  "subscribe",
  "publish",
  "presence",
  "metrics",
  "history",
  "*"
];

type Permission = (typeof allowedPermissions)[number];

interface Permissions {
  [room: string]: string[];
}
Configuration OptionDescriptionType

apiKey
(required)

API keys play an important role in identitfying your app when publising events or conneciing to realtime services. Head over to the dashboard to register for a free account and create an API key if you havn't already.

string

region
(optional)

Specify the closest geographical region to your location. When set, the connection will enter the network through this designated edge entry point.

string

generateTokenResponse()

Responsible for generating a secure token to be sent as an HTTP response, which can be exchanged for access to realtime services via @relaybox/client. To learn more about auth tokens, please refer to the Auth Tokens documentation.

relayBox.generateTokenResponse();

Returns string in JWT format

ParameterDescriptionDefault

clientId
(optional)

Include a clientId to associate an identity with the token. You must provide a clientId for a connection using the generated token to participate in a room's presence set.

-

expiresIn
(optional)

The length of time specified in seconds before the generated token expires and can no longer be used to connect to realtime services

900

permissions
(optional)

Optional dynamic permissions overrides specific to the token being generated. To learn more about permissions please see

Dynamic Permissions

["*"]

Example:

// Generate a token response with a clientId and custom expiry
const tokenResponse = relayBox.generateTokenResponse({
  clientId: 123,
  expiresIn: 300
});

// Generate a token response attaching dynamic permissions
const permissions = {
  myRoom: [
    'subscribe',
    'publish',
    'presence',
    'metrics',
    "history",
  ];
};

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

publish()

Responsible for publishing an event to a named "room".

relayBox.publish();

Returns object of type PublishResponseData

interface PublishResponseData {
  timestamp: number;
  signature: string;
}
ArgumentDescriptionType
1Room Name (required): The name of the room to publish the event tostring
2

Event Name (required): The name of the published event. Connections subscribing to this event by name will receive the event.

string / function
3Data (optional): The data to be sent as the event payloadstring / object
4

clientId (optional): The clientId to attach to the event. If using RelayBox live auth, the corresponding user object will be added to the event before being broadcast.

string / object

Example:

const data = {
  hello: 'world'
};

// Publish an event named 'message' to 'room:one' containing data payload
const response = relayBox.publish('room:one', 'message', data);

verifyAuthToken()

Responsible for verifying an auth token generated from the Auth service or generateTokenResponse() method.

relayBox.verifyAuthToken('xxxxxx.xxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx');
ArgumentDescriptionType
1

Token (required): The jsonwebtoken generated by auth service or generateTokenResponse() method.

string

Returns decoded auth token data

{
  "sub": "12345678-1234-1234-1234-123456789012",
  "publicKey": "_n8__wkmgTul.TdQrg6QQM06J",
  "clientId": "Q5v2aCJEHfuu",
  "tokenType": "id_token",
  "timestamp": "2024-09-15T07:10:16.714Z",
  "iat": 1726384216,
  "exp": 1726384516,
  "iss": "https://relaybox.net"
}

Throws TokenError if the token is invalid.

Example:

relayBox.verifyAuthToken('xxxxxx.xxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx');

verifyWebhookSignature()

Responsible for verifying a webhook request signature. For more information about how to send webhooks, please refer to the documentation.

relayBox.verifyWebhookSignature();
ArgumentDescriptionType
1Request Body (required): The body of the webhook request to be verified.object
2

Request signature (required): The value found the X-Relaybox-Webhook-Signature header included in the webhook request.

string
3Signing Key (required): The signing key associated with the webhook.string

Returns true if the request is valid, otherwise false.

Example:

const body = req.body;
const signature = req.headers['X-Relaybox-Webhook-Signature'];
const signingKey = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx';

relayBox.verifyWebhookSignature(body, signature, signingKey);

    On this page