Manage access

Often times it's necessary to limit users' access to resources, like channels or user metadata, within your application. For instance, you can set up a one-to-one chat room by only allowing two users to send and receive messages in a specific channel.

PubNub's access manager controls client access to resources using time-limited permission tokens. These tokens are granted by PubNub and contain an embedded list of permitted operations for the SDK which has that token. Once PubNub grants a token, it's added to the client SDK's configuration and is sent with every SDK call until it expires or is revoked.

Additionally, you may define a single User ID that can use the token. This way, no other User ID can use that token. If the authorized User ID is different than the one which sends the request, PubNub will deny the request.

Even though it's PubNub that grants the token, you request that a token be granted using an SDK. However, not every SDK instance may request tokens from PubNub. To use the access manager, you must first enable it on the Admin Portal and initialize one of PubNub's SDK using a secretKey. Then, that SDK acts as an intermediary between the clients that request access (SDKs) and PubNub.

User ID / UUID

User ID is also referred to as UUID/uuid in some APIs and server responses but holds the value of the userId parameter you set during initialization.

const pubnub = new PubNub({
   subscribeKey: 'mySubscribeKey',
   publishKey: 'myPublishKey',
   uuid: 'myUniqueUUID',
   secretKey: 'mySecretKey'
});

PNConfiguration.Builder configBuilder = PNConfiguration.builder(new UserId("yourUserId"), "yourSubscribeKey");
configBuilder.publishKey("myPublishKey");
configBuilder.secretKey("mySecretKey");
PubNub pubNub = PubNub.create(configBuilder.build());

PNConfiguration pnconfig = new PNConfiguration();
pnconfig.SubscribeKey = "mySubscribeKey";
pnconfig.PublishKey = "myPublishKey";
pnconfig.SecretKey = "mySecretKey";
pnconfig.Uuid = "myUniqueUuid";
Pubnub pubnub = new Pubnub(pnconfig);

from pubnub.pnconfiguration import PNConfiguration
from pubnub.pubnub import PubNub

pn_config = PNConfiguration()
pn_config.publish_key = "my_publish_key"
pn_config.subscribe_key = "my_subscribe_key"
pn_config.uuid = "my_unique_uuid"
pn_config.secret_key = "my_secret_key"

pubnub = PubNub(pn_config)

final myKeyset = Keyset(
  subscribeKey: 'subscribeKey',
  publishKey: 'publishKey',
  secretKey: 'secretKey',
  userId: UserId('yourUniqueUserId'));

var pubnub = PubNub(defaultKeyset: myKeyset);

val pnConfiguration = PNConfiguration(UserId("myUserId")).apply {
    subscribeKey = "my_subkey"
    publishKey = "my_pubkey"
    secretKey = "my_secretkey"
    secure = true
}
val pubnub = PubNub.create(pnConfiguration)

To issue a grant request, you must make a call from the client SDK, which is the client that wants to have access, to the server SDK, which is the intermediary between clients and PubNub.

The code below grants the thomas_anderson UUID read access to channel-a and read/write access to channel-b, channel-c, and uuid-d for 15 minutes.

pubnub.grantToken(
    {
        ttl: 15,
        authorized_uuid: "thomas_anderson",
        resources: {
            channels: {
                "channel-a": {
                    read: true
                },
               "channel-b": {
                    read: true,
                    write: true
                },
               "channel-c": {
                    read: true,
show all 29 lines

pubnub.grantToken()
    .ttl(15)
    .authorizedUUID("thomas_anderson")
        .channels(Arrays.asList(
                ChannelGrant.name("channel-a").read(),
                ChannelGrant.name("channel-b").read().write(),
                ChannelGrant.name("channel-c").read().write(),
        .uuids(Arrays.asList(
                UUIDGrant.id("uuid-d").get().update()))
        .async(result -> { /* check result */ });

PNResult<PNAccessManagerTokenResult> grantTokenResponse = await pubnub.GrantToken()
    .TTL(15)
    .AuthorizedUuid("thomas_anderson")
    .Resources(new PNTokenResources()
    {
        Channels = new Dictionary<string, PNTokenAuthValues>() {
            { "channel-a", new PNTokenAuthValues() { Read = true } },
            { "channel-b", new PNTokenAuthValues() { Read = true, Write = true } },
            { "channel-c", new PNTokenAuthValues() { Read = true, Write = true } },
        Uuids = new Dictionary<string, PNTokenAuthValues>() {
            { "uuid-d", new PNTokenAuthValues() { Get = true, Update = true } }}
    })
    .ExecuteAsync();
PNAccessManagerTokenResult grantTokenResult = grantTokenResponse.Result;
PNStatus grantTokenStatus = grantTokenResponse.Status;
show all 23 lines

from pubnub.models.consumer.v3.channel import Channel
from pubnub.models.consumer.v3.uuid import UUID

channels = [
    Channel.id("channel-a").read(),
    Channel.id("channel-b").read().write(),
    Channel.id("channel-c").read().write(),
]
uuids = [
    UUID.id("uuid-d").get().update()
]
envelope = pubnub.grant_token()
    .channels(channels)
    .ttl(15)
    .groups(channel_groups)
show all 18 lines

var request = pubnub.requestToken(
var request = pubnub.requestToken(ttl: 15, authorizedUUID: 'thomas_anderson')
    ..add(ResourceType.channel, name: 'channel-a', read: true)
    ..add(ResourceType.channel, name: 'channel-b', read: true, write: true)
    ..add(ResourceType.channel, name: 'channel-c', read: true, write: true)
    ..add(ResourceType.uuid, name: 'uuid-d', get: true, update: true);

  var token = await pubnub.grantToken(request);

var token = await pubnub.grantToken(request);

pubnub.grantToken(
  ttl = 15,
  channels = listOf(
      ChannelGrant.name(name = "channel-a", read = true),
      ChannelGrant.name(name = "channel-b", read = true, write = true),
      ChannelGrant.name(name = "channel-c", read = true, write = true),
  ),
  uuids = listOf(
      UUIDGrant.id(id = "uuid-d", get = true, update = true)
  ),
  authorizedUUID = "thomas_anderson"
).async { result, status ->
  if (status.error) {
      // Handle error
  } else {
show all 18 lines

When you grant permissions, you don't have to manually input every resource you want to grant or change access to. With a single call, you may grant access to multiple channels, channel groups, and UUID metadata using RegEx.

Certain operations, like joining/leaving a channel, or sending a message, among others, generate events sent throughout the PubNub network. Read on to learn how to intercept these events and trigger your own business logic without writing a single line of code.