@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 services library, ensure that npm is installed on the host machine, then run the following command:
npm install @relaybox/rest
Once you have successfully installed the library, the following API reference applies.
RelayBox Class
Instantiate the Relaybox class to enable usage of the server-side SDK.
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 Option | Description | Type |
|---|---|---|
apiKey | Associate an API key with the connection, which you can generate via the dashboard. To create an API key, first register for a free account. | string |
region | 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 real-time services via @relaybox/client. To learn more about auth tokens, please refer to the Auth Tokens documentation.
relayBox.generateTokenResponse();
Returns string in JWT format
| Parameter | Description | Default |
|---|---|---|
clientId | 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 | The length of time specified in seconds before the generated token expires and can no longer be used to connect to real-time services | 900 |
permissions | 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;
}
| Argument | Description | Type |
|---|---|---|
| 1 | Room Name (required): The name of the room to publish the event to | string |
| 2 | Event Name (required): The name of the published event. Connections subscribing to this event by name will receive the event. | string / function |
| 2 | Data (optional): The data to be sent as the event payload | 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');
| Argument | Description | Type |
|---|---|---|
| 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__wkmiZGl.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');
