Grant, change, and revoke permissions

Showing JavaScript examples.

Use a server-side PubNub instance initialized with a secretKey to grant time-limited tokens to your clients, update their permissions by issuing new tokens, and revoke tokens when access must be removed immediately.

Before you start

Confirm you have:

Access Manager enabled on your keyset. See Configure access control.
A server-side PubNub instance initialized with a secretKey. See Initialize a server SDK with a secret key.
For token revocation: the Revoke v3 Token option enabled on the keyset. See Configure access control.

Grant a token

Call grantToken from your server. Specify the authorized User ID, the resource permissions, and the TTL.

The example below grants my-authorized-uuid:

read on channel-a, channel-group-b, and uuid-c.
read and write on channel-b, channel-c, channel-d, and uuid-d.
read on all channels matching the RE2 pattern ^channel-[A-Za-z0-9]$.

1pubnub.grantToken(
  {
      ttl: 15,
      authorized_uuid: "my-authorized-uuid",
      resources: {
          channels: {
              "channel-a": { read: true },
              "channel-b": { read: true, write: true },
              "channel-c": { read: true, write: true },
              "channel-d": { read: true, write: true }
          },
          groups: {
              "channel-group-b": { read: true }
          },
          uuids: {
              "uuid-c": { get: true },
              "uuid-d": { get: true, update: true }
          }
      },
      patterns: {
          channels: {
              "^channel-[A-Za-z0-9]$": { read: true }
          }
      }
  },
  function (status, token) {
      console.log(token)
  });
show all 28 lines

1from pubnub.models.consumer.v3.channel import Channel
2from pubnub.models.consumer.v3.group import Group
3from pubnub.models.consumer.v3.uuid import UUID
4

5channels = [
6    Channel.id("channel-a").read(),
7    Channel.pattern("channel-[A-Za-z0-9]").read(),
8    Channel.id("channel-b").read().write(),
9    Channel.id("channel-c").read().write(),
10    Channel.id("channel-d").read().write()
11]
12channel_groups = [
13    Group.id("channel-group-b").read()
14]
15uuids = [
16    UUID.id("uuid-c").get(),
17    UUID.id("uuid-d").get().update()
18]
19envelope = pubnub.grant_token() \
20    .authorized_uuid("my-authorized-uuid") \
21    .channels(channels) \
22    .groups(channel_groups) \
23    .uuids(uuids) \
24    .ttl(15) \
25    .sync()
26

27token = envelope.result.token
show all 27 lines

1pubnub.grantToken()
  .ttl(15)
  .authorizedUUID("my-authorized-uuid")
  .channels(Arrays.asList(
          ChannelGrant.name("channel-a").read(),
          ChannelGrant.name("channel-b").read().write(),
          ChannelGrant.name("channel-c").read().write(),
          ChannelGrant.name("channel-d").read().write(),
          ChannelGrant.pattern("^channel-[A-Za-z0-9]*$").read()))
  .channelGroups(Collections.singletonList(
          ChannelGroupGrant.id("channel-group-b").read()))
  .uuids(Arrays.asList(
          UUIDGrant.id("uuid-c").get(),
          UUIDGrant.id("uuid-d").get().update()))
  .async(result -> { /* check result */ });

1pubnub.grantToken(
  ttl = 15,
  authorizedUUID = "my-authorized-uuid",
  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),
      ChannelGrant.name(name = "channel-d", read = true, write = true),
      ChannelGrant.pattern(pattern = "^channel-[A-Za-z0-9]*$", read = true)
  ),
  channelGroups = listOf(
      ChannelGroupGrant.id(id = "channel-group-b", read = true)
  ),
  uuids = listOf(
      UUIDGrant.id(id = "uuid-c", get = true),
      UUIDGrant.id(id = "uuid-d", get = true, update = true)
  )
18).sync()
show all 18 lines

1res, status, err := pn.GrantToken().
  TTL(15).
  AuthorizedUUID("my-authorized-uuid").
  Channels(map[string]pubnub.ChannelPermissions{
      "channel-a": { Read: true },
      "channel-b": { Read: true, Write: true },
      "channel-c": { Read: true, Write: true },
      "channel-d": { Read: true, Write: true },
  }).
  ChannelGroups(map[string]pubnub.GroupPermissions{
      "channel-group-b": { Read: true },
  }).
  UUIDs(map[string]pubnub.UUIDPermissions{
      "uuid-c": { Get: true },
      "uuid-d": { Get: true, Update: true },
  }).
  ChannelsPattern(map[string]pubnub.ChannelPermissions{
      "^channel-[A-Za-z0-9]*$": { Read: true },
  }).
  Execute()
show all 20 lines

New SDK available

C-Core (legacy) is still supported. If you are starting a new project, use the new C SDK.

1char* author_uuid = "my-authorized-uuid";
2struct pam_permission cha_perm = {.read=true };
3struct pam_permission cgb_perm = {.read=true };
4struct pam_permission uidc_perm = {.get=true };
5struct pam_permission chb_perm = {.read=true, .write=true };
6struct pam_permission chc_perm = {.read=true, .write=true };
7struct pam_permission chd_perm = {.read=true, .write=true };
8struct pam_permission uidd_perm = {.get=true, .update=true };
9struct pam_permission pat_ch_perm = {.read=true };
10

11int perm_cha = pubnub_get_grant_bit_mask_value(cha_perm);
12int perm_chb = pubnub_get_grant_bit_mask_value(chb_perm);
13int perm_chc = pubnub_get_grant_bit_mask_value(chc_perm);
14int perm_chd = pubnub_get_grant_bit_mask_value(chd_perm);
15int perm_cgb = pubnub_get_grant_bit_mask_value(cgb_perm);
16int perm_uidc = pubnub_get_grant_bit_mask_value(uidc_perm);
17int perm_uidd = pubnub_get_grant_bit_mask_value(uidd_perm);
18int perm_ch_pat = pubnub_get_grant_bit_mask_value(pat_ch_perm);
19

20int ttl_minutes = 15;
21char perm_obj[2000];
22sprintf(perm_obj,"{\"ttl\":%d, \"uuid\":\"%s\", \"permissions\":{\"resources\":{\"channels\":{ \"channel-a\":%d, \"channel-b\":%d, \"channel-c\":%d, \"channel-d\":%d }, \"groups\":{ \"channel-group-b\":%d }, \"uuids\":{ \"uuid-c\":%d, \"uuid-d\":%d }}, \"patterns\":{\"channels\":{ \"channel-[A-Za-z0-9]\":%d }, \"groups\":{ }, \"uuids\":{ }},\"meta\":{ }}}", ttl_minutes, author_uuid, perm_cha, perm_chb, perm_chc, perm_chd, perm_cgb, perm_uidc, perm_uidd, perm_ch_pat);
23res = pubnub_grant_token(gtp, perm_obj);
24if (PNR_STARTED == res) {
25    res = pubnub_await(gtp);
26    if (PNR_OK == res) {
27        pubnub_chamebl_t grant_token_resp = pubnub_get_grant_token(gtp);
28        printf("pubnub_grant_token() Response from Pubnub: %s\n", grant_token_resp.ptr);
29    }
30}
show all 30 lines

1PNResult<PNAccessManagerTokenResult> grantTokenResponse = await pubnub.GrantToken()
2    .TTL(15)
3    .AuthorizedUuid("my-authorized-uuid")
4    .Resources(new PNTokenResources()
5    {
6        Channels = new Dictionary<string, PNTokenAuthValues>() {
7            { "channel-a", new PNTokenAuthValues() { Read = true } },
8            { "channel-b", new PNTokenAuthValues() { Read = true, Write = true } },
9            { "channel-c", new PNTokenAuthValues() { Read = true, Write = true } },
10            { "channel-d", new PNTokenAuthValues() { Read = true, Write = true } }},
11        ChannelGroups = new Dictionary<string, PNTokenAuthValues>() {
12            { "channel-group-b", new PNTokenAuthValues() { Read = true } } },
13        Uuids = new Dictionary<string, PNTokenAuthValues>() {
14            { "uuid-c", new PNTokenAuthValues() { Get = true } },
15            { "uuid-d", new PNTokenAuthValues() { Get = true, Update = true } }}
16    })
17    .Patterns(new PNTokenPatterns()
18    {
19        Channels = new Dictionary<string, PNTokenAuthValues>() {
20            { "channel-[A-Za-z0-9]", new PNTokenAuthValues() { Read = true } }}
21    })
22    .ExecuteAsync();
23PNAccessManagerTokenResult grantTokenResult = grantTokenResponse.Result;
24PNStatus grantTokenStatus = grantTokenResponse.Status;
25if (!grantTokenStatus.Error && grantTokenResult != null)
26{
27    Console.WriteLine(pubnub.JsonPluggableLibrary.SerializeToJsonString(grantTokenResult));
28}
29else
30{
31    Console.WriteLine(pubnub.JsonPluggableLibrary.SerializeToJsonString(grantTokenStatus));
32}
show all 32 lines

1var request = pubnub.requestToken(
2    ttl: 15, authorizedUUID: 'my-authorized-uuid')
3..add(ResourceType.channel, name: 'channel-a', read: true)
4..add(ResourceType.channelGroup, name: 'channel-group-b', read: true)
5..add(ResourceType.uuid, name: 'uuid-c', get: true)
6..add(ResourceType.channel, name: 'channel-b', read: true, write: true)
7..add(ResourceType.channel, name: 'channel-c', read: true, write: true)
8..add(ResourceType.channel, name: 'channel-d', read: true, write: true)
9..add(ResourceType.uuid, name: 'uuid-d', get: true, update: true)
10..add(ResourceType.channel, pattern: 'channel-[A-Za-z0-9]', read: true);
11

12var token = await pubnub.grantToken(request);
13print('grant token = $token');

1$pubnub->grantToken()
  ->ttl(15)
  ->authorizedUuid('my-authorized-uuid')
  ->addChannelResources([
      'channel-a' => ['read' => true],
      'channel-b' => ['read' => true, 'write' => true],
      'channel-c' => ['read' => true, 'write' => true],
      'channel-d' => ['read' => true, 'write' => true],
  ])
  ->addChannelGroupResources([
      'channel-group-b' => ['read' => true],
  ])
  ->addUuidResources([
      'uuid-c' => ['get' => true],
      'uuid-d' => ['get' => true, 'update' => true],
  ])
  ->addChannelPatterns([
      '^channel-[A-Za-z0-9]$' => ['read' => true],
  ])
show all 19 lines

1pubnub.grant_token(
  ttl: 15,
  authorized_uuid: "my-authorized-uuid",
  channels: {
      "channel-a": Pubnub::Permissions.res(read: true),
      "channel-b": Pubnub::Permissions.res(read: true, write: true),
      "channel-c": Pubnub::Permissions.res(read: true, write: true),
      "channel-d": Pubnub::Permissions.res(read: true, write: true),
      "^channel-[A-Za-z0-9]$": Pubnub::Permission.pat(read: true)
  },
  channel_groups: {
      "channel-group-b": Pubnub::Permissions.res(read: true)
  },
  uuids: {
      "uuid-c": Pubnub::Permissions.res(get: true),
      "uuid-d": Pubnub::Permissions.res(get: true, update: true)
  },
  http_sync: true
19);
show all 19 lines

Authorized UUID vs UUIDs

The authorized_uuid field binds the token to one User ID that can use it. The uuids key inside resources grants permissions to access other users' metadata. These are different fields with different purposes.

Token size limit

Access Manager grantToken() requests over 32 KiB return HTTP 414 (URI Too Long). Prefer RE2 patterns over long resource lists, and keep resource names short.

Change permissions

To change a user's permissions, grant a new token with the updated resource list and return it to the client. The client sets the new token using setToken and uses it for subsequent calls.

To update a token on the client after receiving it, see Initialize a client SDK with an auth key.

Revoke a token

Revoking a token immediately blocks all requests that use it. A request that uses a revoked token fails with 403 Revoked Token. Each revoke call accepts a single token, so batch revocation isn't supported.

Revocation delay

Token revocation can take up to one minute to take effect, because PubNub caches a token's non-revoked state for that long.A revoked token's deny-list entry persists until the token's original TTL would have expired.A revoked token can't be re-enabled.

1const token = await pubnub.revokeToken("p0AkFl043rhDdHRsple3KgQ3NwY6BDcENnctokenVzcqBDczaWdYIGOAeTyWGJI");

1PNResult<PNAccessManagerRevokeTokenResult> revokeTokenResponse = await pubnub
2    .RevokeToken()
3    .Token("p0thisAkFl043rhDdHRsCkNyZXisRGNoYW6hanNlY3JldAFDZ3Jwsample3KgQ3NwY6BDcGF0pERjaGFuoENnctokenV")
4    .ExecuteAsync();
5PNAccessManagerRevokeTokenResult revokeTokenResult = revokeTokenResponse.Result;
6PNStatus revokeTokenStatus = revokeTokenResponse.Status;
7if (!revokeTokenStatus.Error && revokeTokenResult != null)
8{
9    Console.WriteLine("Revoke token success");
10}
11else
12{
13    Console.WriteLine(pubnub.JsonPluggableLibrary.SerializeToJsonString(revokeTokenStatus));
14}

Debug Console

To generate or revoke a test token without writing code, use the Access Manager tab of the Debug Console in the Admin Portal.

Initialize a client SDK with an auth key. Set the granted token on the client.
Check available permissions. Decode a token to inspect its embedded permissions.
Change or extend access. Strategies for updating tokens before they expire.
Update an expired token. Handle 403 errors when a token has expired.
Permission model. Available permission flags per resource type.
Operations to permissions mapping. Which permission each PubNub API operation requires.

Before you start​

Grant a token​

New SDK available

Authorized UUID vs UUIDs

Token size limit

Change permissions​

Revoke a token​

Revocation delay

Debug Console

Related pages​

Before you start

Grant a token

Change permissions

Revoke a token

Related pages