Access control and permissions management

Access Manager v2 is deprecated

This documentation describes Access Manager v3.

If you use Access Manager in v2, migrate to the latest version (v3).

When you build an in‑app messaging app, you may need rules to limit access to channels and user metadata. Access Manager lets you set a clear permission schema and decide who can do what. This protects your app from unauthorized access.

Access Manager (v3) is a token‑based access control system for PubNub resources: channels, channel groups, and user IDs. You can make a 1:1 chat private by allowing only two users to read and write. You can also make a channel public by granting access to all users. You can define many permissions in one API call by listing resources or using regular‑expression patterns.

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.

Apps that use Access Manager create user tokens with individual permissions. PubNub generates these tokens. The client gets a token from your server and sends it with each PubNub API request.

Accepted tokens

Access Manager uses PubNub‑generated cryptographic tokens to define permissions for channels, groups, and metadata. External tokens (such as JWTs) aren’t supported.

Configuration

Enable Access Manager for your app’s keyset in the Admin Portal.

Public Admin Portal demo

Want to browse through the Admin Portal without creating an account? Explore it through the Public Demo that shows examples of most PubNub features for transport and logistics use case.

Option	Description
Revoke v3 Token	Invalidate a token so it can’t authenticate access to PubNub resources.

Authorization flow

Three actors participate in the authorization process:

• Server - A centralized server manages access. Only the server can request grants with the secretKey. Expose an API so clients can get new or updated tokens. Use the server to validate logins, set permissions, and specify the authorized_uuid.

• Client device - A client runs on one device. It requests a token from the server, sets it as the authKey, and uses it for API calls to channels, channel groups, and user ID metadata. The client refreshes the token before it expires.

• PubNub - PubNub provides APIs for both servers and clients. Servers call the grant API to generate or refresh tokens. Clients pass tokens with requests (publish, subscribe). PubNub validates that the user has the required permissions.

A typical client authorization could look as follows:

1. Upon login, the client requests authorization.

2. The server uses the secretKey to request a token with the needed permissions for the authorized User ID.

3. PubNub returns a signed, time‑limited token.

4. The server returns the token to the client.

5. The client sets the token (the authKey) in the SDK configuration.

6. The client uses the token for API calls until it expires or is revoked, then requests a new token.

This flow ensures only authorized users access specific PubNub resources.

Server-side operations

Once your server can grant tokens, clients use those tokens securely.

Use a centralized server that initializes a server‑side PubNub SDK with a secretKey. Only the server can request permission grants.

Initialize with a secret key

The secretKey lets you give clients access to PubNub resources, change access levels, and remove permissions. When you initialize PubNub with the secretKey, you get root permissions for Access Manager. Servers get read and write access to all resources, so you do not need to grant extra access for server calls.

Paid plans support secret key rotation. It manages and expires up to five keys, including the current key.

Secret key security

Use the secretKey only on a secure server. Never expose it to client devices. If it is compromised, regenerate it in the Admin Portal.

Node.js

const pubnub = new PubNub({
    subscribeKey: "mySubscribeKey",
    publishKey: "myPublishKey",
    secretKey: "mySecretKey",
    userId: "myUniqueUserId"
  });

Python

pn_config = PNConfiguration()
pn_config.subscribe_key = "my_subscribe_key"
pn_config.publish_key = "my_publish_key"
pn_config.secret_key = "my_secret_key"
pn_config.user_id = "my_unique_user_id"
pubnub = PubNub(pn_config)

Java

PNConfiguration.Builder configBuilder = PNConfiguration.builder(new UserId("yourUserId"), "yourSubscribeKey");
// publishKey from Admin Portal (only required if publishing)
configBuilder.publishKey("PublishKey");
configBuilder.secretKey("mySecretKey");
PubNub pubNub = PubNub.create(configBuilder.build());

Kotlin

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

Go

pnconfig := pubnub.NewConfig()
  pnconfig.SubscribeKey = "MySubscribeKey"
  pnconfig.PublishKey = "MyPublishKey"
  pnconfig.SecretKey = "MySecretKey"
  pnconfig.SetUserId(UserId("myUniqueUserId"))
  pn := pubnub.NewPubNub(pnconfig)

C#

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

Dart

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

PHP

use PubNub\PNConfiguration;
$pnConfiguration = new PNConfiguration();
$pnConfiguration->setSubscribeKey("MySubscribeKey");
$pnConfiguration->setPublishKey("MyPublishKey");
$pnConfiguration->setSecretKey("MySecretKey");
$pnConfiguration->setUserId("MyUniqueUserId");

Ruby

pubnub = Pubnub.new(
    subscribe_key: 'my_subscribe_key',
    publish_key: 'my_publish_key',
    secret_key: 'my_secret_key',
    user_id: 'myUniqueUserId'
);

Grant permissions

PubNub enforces access with time‑limited grant tokens.

After you enable Access Manager, call PubNub to grant a token. Specify the authorized User ID, the resource permissions (lists or RegEx), and the ttl (Time To Live).

An authorized User ID can have permissions for:

• Channels
• Channel groups
• User IDs (which are other users' object metadata, such as their names or avatars)

Once the grant is successful, the server responds to the client device's authentication request by returning a token with embedded permissions.

The code below grants the my-authorized-uuid:

• Read access to channel-a, channel-group-b, and uuid-c.
• Read/write access to channel-b, channel-c, channel-d, and uuid-d.
• Read access to all channels that match the channel-[A-Za-z0-9] RegEx pattern.

Node.js

pubnub.grantToken(
    {
        ttl: 15,
        authorized_uuid: "my-authorized-uuid",
        resources: {
            channels: {
                "channel-a": {
                    read: true
                },
               "channel-b": {
                    read: true,
                    write: true
                },
               "channel-c": {
                    read: true,

show all 48 lines

Python

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

channels = [
    Channel.id("channel-a").read(),
    Channel.pattern("channel-[A-Za-z0-9]").read(),
    Channel.id("channel-b").read().write(),
    Channel.id("channel-c").read().write(),
    Channel.id("channel-d").read().write()
]
channel_groups = [
    Group.id("channel-group-b").read()
]
uuids = [

show all 27 lines

Java

pubnub.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 */ });

Kotlin

pubnub.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),

show all 19 lines

Go

res, 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,
                },

show all 40 lines

C

char* author_uuid = "my-authorized-uuid";
struct pam_permission cha_perm = {.read=true };
struct pam_permission cgb_perm = {.read=true };
struct pam_permission uidc_perm = {.get=true };

struct pam_permission chb_perm = {.read=true, .write=true };
struct pam_permission chc_perm = {.read=true, .write=true };
struct pam_permission chd_perm = {.read=true, .write=true };
struct pam_permission uidd_perm = {.get=true, .update=true };

struct pam_permission pat_ch_perm = {.read=true };

int perm_cha = pubnub_get_grant_bit_mask_value(cha_perm);
int perm_chb = pubnub_get_grant_bit_mask_value(chb_perm);
int perm_chc = pubnub_get_grant_bit_mask_value(chc_perm);

show all 35 lines

C#

PNResult<PNAccessManagerTokenResult> grantTokenResponse = await pubnub.GrantToken()
    .TTL(15)
    .AuthorizedUuid("my-authorized-uuid")
    .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 } },
            { "channel-d", new PNTokenAuthValues() { Read = true, Write = true } }},
        ChannelGroups = new Dictionary<string, PNTokenAuthValues>() {
            { "channel-group-b", new PNTokenAuthValues() { Read = true } } },
        Uuids = new Dictionary<string, PNTokenAuthValues>() {
            { "uuid-c", new PNTokenAuthValues() { Get = true } },
            { "uuid-d", new PNTokenAuthValues() { Get = true, Update = true } }}

show all 32 lines

Dart

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

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

PHP

$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],

show all 19 lines

Ruby

pubnub.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
            ),

show all 39 lines

Token size limits

A token stores all access mappings. As you add permissions, the token grows. Larger tokens increase HTTP request size.

Requests that exceed 32 KiB fail with 414 URI Too Long. To stay within limits:

• Prefer RegEx patterns over long resource lists.
• Keep resource names short and consistent.

See channel naming convention or contact support for help.

TTL

ttl is the number of minutes before granted permissions expire. It is required for every grant. There is no default.

The minimum is 1 (1 minute). The maximum is 43200 (30 days). If you need a higher limit, contact support.

RegEx

You can grant access in a single API call. Use either:

• A single resource or a list of resources the authorized UUID can access.
• A pattern‑based sequence of UUIDs, channels, or channel groups using regular expressions.

To succeed, specify permissions for at least one UUID, channel, or channel group (resource list or pattern).

Authorized UUID

For a higher level of security, you can specify one top-level authorized UUID in the grant payload. When specified, this UUID will be embedded in the token and returned by the grant request. This ensures that any request to PubNub that uses that token has to come from that authorized UUID. Otherwise, PubNub will reject the request and deny access to the resources.

Authorized UUID vs UUIDs

The grant request body contains the uuids key which defines permissions required to access the other UUIDs' (users') metadata. The UUIDs contained within have nothing to do with the UUID authorized to use the token. To allow a UUID to use a particular token, specify this UUID as an authorized one (authorized_uuid). The value of that parameter must be an instance of a preexisting client's UUID that was set during the initialization of its PubNub object. For more information about setting UUIDs, refer to Identity Management.

Change permissions

Apps often change a user's permissions. For example, add or remove a user from a channel. The server requests a new grant and returns the token to the client.

Revoke permissions

Enable token revoke

To revoke tokens, you must first enable this feature on the Admin Portal. To do that, navigate to your app's keyset and mark the Revoke v3 Token checkbox in the ACCESS MANAGER section.

Access Manager lets you revoke a token. Calls that use a revoked token fail with a 403 Revoked Token error. Revoking tokens is useful when you need to remove access quickly.

You can only revoke a valid token previously obtained through a token grant request. Each revoked token is stored in a deny list (usual charges apply) allowing for quick lookup of revoked tokens.

Consider these constraints when revoking tokens:

• You can only enable the token revoke feature if the token ttl for the subkey is less than or equal to 30 days. If that ttl value doesn't meet your requirements, contact support.
• If support changes your token's ttl to exceed 30 days, you can disable the token revoke functionality, but can't re-enable it using the Admin Portal. To do that, contact support.
• You can only revoke one token per one revoke call, batch revokes aren't supported.
• It may take up to 1 minute for the token revoke request to take effect.
• You can't re-enable a revoked token.

Node.js

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

Python

envelope = pubnub.revoke_token("p0thisAkFl043rhDdHRsCkNyZXisRGNoYW6hanNlY3JldAFDZ3Jwsample3KgQ3NwY6BDcGF0pERjaGFuoENnctokenV")
    .sync()

Java

pubnub.revokeToken()
    .token("p0thisAkFl043rhDdHRsCkNyZXisRGNoYW6hanNlY3JldAFDZ3Jwsample3KgQ3NwY6BDcGF0pERjaGFuoENnctokenV")
    .sync()

Kotlin

pubnub.revokeToken("p0thisAkFl043rhDdHRsCkNyZXisRGNoYW6hanNlY3JldAFDZ3Jwsample3KgQ3NwY6BDcGF0pERjaGFuoENnctokenV")
    .sync()

Go

res, status, err := pn.RevokeToken()
    .Token("p0thisAkFl043rhDdHRsCNlY3JldAFDZ3Jwsample3KgQ3NwY6BDENnctokenV")
    .Execute()

C#

PNResult<PNAccessManagerRevokeTokenResult> revokeTokenResponse = await pubnub
    .RevokeToken()
    .Token("p0thisAkFl043rhDdHRsCkNyZXisRGNoYW6hanNlY3JldAFDZ3Jwsample3KgQ3NwY6BDcGF0pERjaGFuoENnctokenV")
    .ExecuteAsync();
PNAccessManagerRevokeTokenResult revokeTokenResult = revokeTokenResponse.Result;
PNStatus revokeTokenStatus = revokeTokenResponse.Status;
if (!revokeTokenStatus.Error && revokeTokenResult != null)
{
    Console.WriteLine("Revoke token success");
}
else
{
    Console.WriteLine(pubnub.JsonPluggableLibrary.SerializeToJsonString(revokeTokenStatus));
}

Dart

await pubnub.revokeToken("p0AkFl043rhDdHRsple3KgQ3NwY6BDcENnctokenVzcqBDczaWdYIGOAeTyWGJI");

PHP

$pubnub->revokeToken("p0thisAkFl043rhDdHRsCkNyZXisRGNoYW6hanNlY3JldAFDZ3Jwsample3KgQ3NwY6BDcGF0pERjaGFuoENnctokenV")
    ->sync();

Ruby

pubnub.revoke_token(token: "p0thisAkFl043rhDdHRsCkNyZXisRGNoYW6hanNlY3JldAFDZ3Jwsample3KgQ3NwY6BDcGF0pERjaGFuoENnctokenV", http_sync: true)

Token caching

PubNub caches tokens for performance. If a token isn’t in the deny list, PubNub caches that state for up to one minute.

If the token was found in the deny list, the system will cache this response for the ttl of the token.

Client-side operations

After the server grants tokens, clients use them as follows.

In general, client applications don't generate tokens, but rather request tokens from server APIs, which handle authentication and permissions logic. The syntax and implementation of these client and server APIs are up to the developer. This section outlines operations that a client may take after getting a token from the centralized server applications.

Initialize with an authKey

When a user logs in, the client sends data to the server. The server validates identity, determines permissions, and specifies the authorized UUID. It generates a token using the secretKey and receives the token (authKey) from PubNub. The server returns the token to the client.

To securely configure client-side access, use the token received from your server. This key ensures clients have the necessary permissions without exposing sensitive information like the secretKey.

Here's how to set up the client SDK with the token:

JavaScript

const pubnub = new PubNub({
  subscribeKey: "mySubscribeKey",
  publishKey: "myPublishKey",
  userId: "myUniqueUserId",
  authKey: "yourAuthKey" // Include the authKey here
});

Python

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

pnconfig = PNConfiguration()
pnconfig.subscribe_key = "my_subscribe_key"
pnconfig.publish_key = "my_publish_key"
pnconfig.user_id = "my_unique_user_id"
pnconfig.auth_key = "your_auth_key"  # Include the authKey here
pnconfig.ssl = True

pubnub = PubNub(pnconfig)

Swift

```swift
import PubNub

let config = PubNubConfiguration(
  publishKey: "myPublishKey",
  subscribeKey: "mySubscribeKey",
  userId: "myUniqueUserId",
  authKey: "yourAuthKey"  // Include the authKey here
)

let pubnub = PubNub(configuration: config)

Objective-C

#import <PubNub/PubNub.h>

// Set up the PubNub configuration
PNConfiguration *config = [PNConfiguration configurationWithPublishKey:@"myPublishKey"
                                                           subscribeKey:@"mySubscribeKey"
                                                                 userID:@"myUniqueUserId"];
config.authKey = @"yourAuthKey"; // Include the authKey here

// Initialize the PubNub client
self.client = [PubNub clientWithConfiguration:config];

Go

package main

import pubnub "github.com/pubnub/go"

func main() {
    config := pubnub.NewConfigWithUserId("myUniqueUserId")
    config.SubscribeKey = "mySubscribeKey"
    config.PublishKey = "myPublishKey"
    config.AuthKey = "yourAuthKey" // Include the authKey here
    config.Secure = true

    pn := pubnub.NewPubNub(config)
    // Now you can use `pn` to interact with PubNub services
}

Unity

using PubnubApi;

public class PubNubSetup
{
    public void InitializePubNub()
    {
        // Initialize the PNConfiguration with a unique UserId
        PNConfiguration pnConfiguration = new PNConfiguration(new UserId("myUniqueUserId"));
        
        // Set the SubscribeKey and PublishKey from Admin Portal
        pnConfiguration.SubscribeKey = "mySubscribeKey";
        pnConfiguration.PublishKey = "myPublishKey";
        
        // Include the AuthKey here
        pnConfiguration.AuthKey = "yourAuthKey";

show all 25 lines

C#

using PubnubApi;

public class PubNubSetup
{
    public void InitializePubNub()
    {
        // Initialize the PNConfiguration with a unique UserId
        PNConfiguration pnConfiguration = new PNConfiguration(new UserId("myUniqueUserId"));
        
        // Set the SubscribeKey and PublishKey from Admin Portal
        pnConfiguration.SubscribeKey = "mySubscribeKey";
        pnConfiguration.PublishKey = "myPublishKey";
        
        // Include the AuthKey here
        pnConfiguration.AuthKey = "yourAuthKey";

show all 25 lines

Dart

import 'package:pubnub/pubnub.dart';

void main() {
  // Create a keyset with the required parameters
  final myKeyset = Keyset(
    subscribeKey: 'mySubscribeKey',
    publishKey: 'myPublishKey',
    authKey: 'yourAuthKey', // Include the authKey here
    userId: UserId('myUniqueUserId'),
  );

  // Initialize the PubNub instance with the keyset
  final pubnub = PubNub(defaultKeyset: myKeyset);

  // You can now use `pubnub` to interact with PubNub services

show all 16 lines

PHP

<?php

use PubNub\PNConfiguration;
use PubNub\PubNub;

// Create a PNConfiguration with a unique UserId
$pnConfiguration = new PNConfiguration();
$pnConfiguration->setSubscribeKey("mySubscribeKey");
$pnConfiguration->setPublishKey("myPublishKey");
$pnConfiguration->setUserId("myUniqueUserId");
$pnConfiguration->setAuthKey("yourAuthKey"); // Include your authKey here
$pnConfiguration->setSecure(true); // Use SSL

// Initialize the PubNub instance with the configuration
$pubnub = new PubNub($pnConfiguration);

show all 17 lines

Ruby

require 'pubnub'

# Initialize the PubNub client with the necessary parameters
pubnub = Pubnub.new(
    subscribe_key: 'mySubscribeKey',
    publish_key: 'myPublishKey',
    user_id: 'myUniqueUserId',
    auth_key: 'yourAuthKey', # Include your authKey here
    ssl: true # Use SSL
)

# You can now use `pubnub` to interact with PubNub services

Check permissions

Access Manager v3 allows you to decode your permissions by parsing a token. You don't need a secretKey to request token details.

Use this method whenever you want to:

• Debug an issue to diagnose the reason for a failing request that returns a 403.
• Inspect privileges embedded in the token to check if you have access to a given resource.

Request token details:

JavaScript

pubnub.parseToken("yourToken")

Python

pubnub.parse_token("your_token")

Java

pubnub.parseToken("yourToken")

Kotlin

pubnub.parseToken("yourToken")

Swift

pubnub.parse(token: "yourToken")

Objective-C

PNPAMToken *token = [self.client parseAuthToken:@"yourToken"];
NSLog(@"Token permissions: %@", token);

Go

pubnub.ParseToken("YourToken") // Given the "pubnub" package is imported: import (pubnub "github.com/pubnub/go/v5")

C

char* cbor_data = pubnub_parse_token(<pubnub_context>, "yourToken");

Unity

pubnub.ParseToken("yourToken")

C#

pubnub.ParseToken("yourToken")

Dart

pubnub.parseToken("yourToken")

PHP

$pubnub->parseToken("yourToken");

Ruby

pubnub.parse_token("yourToken")

See a sample response:

{
   "version":2,
   "timestamp":1629394579,
   "ttl":15,
   "authorized_uuid": "user1",
   "resources":{
      "uuids":{
         "user1":{
            "read":false,
            "write":false,
            "manage":false,
            "delete":false,
            "get":true,
            "update":true,
            "join":false

show all 76 lines

Request a new token

When a client makes an API request using a token that has expired or has been revoked, PubNub API will respond with the 403 Token is expired or 403 Token revoked error message. To renew access, the client should include the logic that prompts the server to request a new token to be generated by PubNub. The authorization flow looks similar to the already described login example. In both cases the server first includes the application-specific logic to validate that the request came from an authorized client, and then makes a PubNub token grant request:

After either a login or a token refresh request from the client, the server passes the newly generated token back to the client device, which then needs to update its configuration and set the new token. Refer to the Token expiration for more information.

JavaScript

pubnub.setToken("newToken")

Python

pubnub.set_token("new_token")

Java

pubnub.setToken("newToken")

Kotlin

pubnub.setToken("newToken")

Swift

pubnub.set(token: "newToken")

Objective-C

[self.client setAuthToken:@"NewToken"];

Go

pn.SetToken("NewToken")

C

pubnub.pubnub_set_token(<pubnub_context>, "NewToken")

Unity

pubnub.SetToken("newToken")

C#

pubnub.SetAuthToken("newToken")

Dart

pubnub.setToken("newToken")

PHP

$pubnub->setToken("newToken");

Ruby

pubnub.set_token("newToken")

Token expiration

PubNub checks the token on every authenticated request. Each token has a ttl. When it expires, replace the token.

Using an expired token

If the client sends an expired token, the PubNub server will return a 403 with a respective error message. When you set a new token, calling pubnub.reconnect() (name may vary across SDKs) is necessary.

Update a valid token

To change or extend access to resources, grant a new token with modified permissions.

To address the token expiration effectively, we recommend that you implement one of the following token refresh strategies:

1. The server maintains a list of expiry times, automatically refreshes soon-to-be-stale tokens, and proactively sends the new token to the clients. Clients should respond to these updates by updating the token in the SDK.

2. The client checks the ttl whenever it receives a token and sets a timer to make a refresh request. The server supports a refresh API.

3. The client supports the logic that handles 403 responses, makes a just-in-time token request, updates the SDK upon getting a new token, reconnects, and retries the request that fails.

Update an expired token

The steps to update a token that is past its ttl are similar to updating a valid token with a few exceptions. When your application tries to authenticate using an expired token, PubNub returns an HTTP 403 error, the request isn't retried automatically, and you must reconnect to PubNub.

To update an expired token, we recommend that your token refresh strategy covers the following steps:

1. The client requests a new token from the server and sets it using the pubnub.setToken() method (name may vary across SDKs).

2. Once the new token is set, the client reconnects to PubNub.

3. The client retries the failed request.

Permissions

Access Manager v3 grants permissions for these resources. The table lists the allowed flags for each resource:

Resource	Available Permissions
Channel	read, write, delete, get, update, manage, join
Channel Group	read, manage
UUID Metadata	get, update, delete

Operations to permissions mapping

The following tables show the mappings of API operations to resources and permissions.

Chat SDK method to required Access Manager permission mapping

For information about which Chat SDK methods require what Access Manager permissions, refer to Security and permissions.

Pub/Sub

PubNub Operation	Resource	Permission
Publish on channel	Channel	Write
Signal on channel	Channel	Write
Subscribe to channel	Channel	Read
Subscribe to presence channel	Presence Channel (-pnpres)	Read
Subscribe to channel group	Channel Group	Read
Subscribe to presence channel group	Presence Channel Group (-pnpres)	Read
Unsubscribe from channel	Channel	None required
Unsubscribe from channel group	Channel Group	None required

Presence

PubNub Operation	Resource	Permission
Here Now	Channel	Read
Where Now	Channel	none required
Get State	Channel	Read
Set State	Channel	Read

Message Persistence

PubNub Operation	Resource	Permission
History - Fetch Messages	Channel	Read
Message Counts	Channel	Read
Delete Messages	Channel	Delete

File sharing

PubNub Operation	Resource	Permission
Send file on channel	Channel	Write
List files	Channel	Read
Download file	Channel	Read
Delete file	Channel	Delete

Channel groups

PubNub Operation	Resource	Permission
Add Channels to channel group	Channel Group	Manage
Remove Channels from channel group	Channel Group	Manage
List Channels in channel group	Channel Group	Read
Remove channel group	Channel Group	Manage

App Context

PubNub Operation	Resource	Permission
Set user metadata	UUID	Update
Delete user metadata	UUID	Delete
Get user metadata	UUID	Get
Get all user metadata	UUID	Managed by the Disallow Get All User Metadata option in the App Context configuration on the Admin Portal. When this option is unchecked, and Access Manager is enabled in an app, you can get metadata of all users without the need to define that in the permissions schema included in the authentication token.
Set channel metadata	Channel	Update
Delete channel metadata	Channel	Delete
Get channel metadata	Channel	Get
Get all channel metadata	Channel	Managed by the Disallow Get All Channel Metadata option in the App Context configuration on the Admin Portal. When this option is unchecked, and Access Manager is enabled in an app, you can get metadata of all channels without the need to define that in the permissions schema included in the authentication token.
Set channel members	Channel	Manage
Remove channel members	Channel	Manage
Get channel members	Channel	Get
Set channel memberships	Channel, UUID	Channels: Join UUID: Update
Remove channel memberships	Channel, UUID	Channels: Join UUID: Update
Get channel memberships	UUID	Get

Mobile Push Notifications

PubNub Operation	Resource	Permission
Register channel for push	Channel	Read
Remove channel's push registration	Channel	Read

Message Actions

PubNub Operation	Resource	Permission
Add Message Action	Channel	Write
Remove Message Action	Channel	Delete
Get Message Actions	Channel	Read
Get History with Actions	Channel	Read