Satori Docs

Your definitive guide to subscribing and publishing live data

Access Control Direct link

This article presents an overview of access control in Satori RTM. You will learn how access control works out of the box and how to customize roles and permissions for stronger access control.

Satori controls access to channels using roles. Roles are configured in Satori projects with a set of channel permissions and one role secret key.  A role can have the publish and/or subscribe permissions, i.e. to write and read, for each channel. 

The following diagram depicts the relationships among the entities that control access to RTM. An arrow indicates an one-to-many relationship, and a line indicates an one-to-one relationship.


Each project comes with the “default” role that has the permissions to publish and subscribe to all channels. When a client establishes a connection to RTM, the client is connected as the “default” role. The client can continue to operate on the unauthenticated connection, provided, channel permissions allow it. It can publish or subscribe as the “default” role.

For a stronger access control, such as restricting access for a particular role to particular channels, create and use custom roles. Your client can acquire different permissions by authenticating as a different custom role. This is done in a two-step process using the Handshake and then Authenticate PDUs:

  • If using the SDK, authenticate the connection with one of the client SDKs in your app. See below for code samples.

You cannot authenticate as the “default” role. RTM returns an error.

We recommend that you change the permissions of the “default” role first if you want to use custom roles to control access.

To summarize, the high-level process to authenticate and authorize as a custom role is:

  1. Add a custom role in your Dev Portal project and grant the role the permission to subscribe or publish to the specific channel. See Manage Roles in the Dev Portal.

  2. In your client app, authenticate to specific channels as the custom role using the role name and the role secret key.

RTM SDK Examples for Access Control Direct link

The example below shows how to authenticate the RTM client and handle authentication errors. Replace the RTM credential placeholders with the values obtained from your project in Dev Portal. Note that authentication is required only if you publish, subscribe or perform other operations with a restricted channel. Channel permissions are configured in the Dev Portal.

var RTM = require('satori-rtm-sdk');

var endpoint = 'YOUR_ENDPOINT';
var appkey = 'YOUR_APPKEY';
var role = 'YOUR_ROLE';
var roleSecret = 'YOUR_SECRET';

var roleSecretProvider = RTM.roleSecretAuthProvider(role, roleSecret);
var client = new RTM(endpoint, appkey, {
  authProvider: roleSecretProvider,
});

client.on('error', function (e) {
  console.log('Error occurred', e);
});

client.on('enter-connected', function () {
  console.log('Connected to Satori RTM and authenticated as ' + role);
});

client.start();