Access Manager v3 Migration Guide

Access Manager v3 is a cryptographic, token‑based permission system that lets you regulate client access to PubNub resources, such as channels, channel groups, and User IDs. Access Manager helps you increase security and prevent access without explicit permission. This guide is for developers using Access Manager v2.

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.

The v3 model lowers latency and improves stability. Complexity moves from authorization to grant requests. Tokens returned by the grant API work immediately. Clients are less likely to see latency on API calls. v3 adds security options and more flexible permission checks. See the Access Manager v3 feature description.

If your app uses v2 today, PubNub continues to process requests. We recommend migrating to v3. This guide summarizes the differences, compares data flows, and outlines migration steps.

Differences between v2 and v3

See all the major differences between the two versions:

Feature	Access Manager v2	Access Manager v3
Authentication method	Authentication key generated by the client.	Token generated by PubNub upon a grant request made by the server.
Permissions storage	Permissions are stored as an access control list (ACL) in the database on the PubNub server.	Permissions are embedded in a token (self-contained).
Permissions expiration	Each resource has its own unique ttl (time to live).	There is one ttl that's set at a token level.
Authorization check latency	Database lookup is required and that increases latency.	Instant check as permissions are embedded in the token.
Grant latency	High latency	Low latency - clients can connect immediately after they receive tokens.
Pattern-based permissions	It supports only one-level wildcard notations (a.*) for the channel resource.	It supports RegEx for channels, groups (channel groups), and uuids.
Multiple permission grants	You must make separate API calls for multiple permission sets.	You can make a single API call to define multiple permission sets for a given authorized User ID.

Differences in data flows

Typical PubNub solutions that use Access Manager include a centralized, customer-developed server application that initializes a PubNub SDK with a secretKey allowing the server to make calls to the PubNub grant API. Clients connect with this server through application-specific interfaces developed by the customer. The following descriptions show examples of client-server interactions initiated by a user logging in to the client device. The idea behind it is to demonstrate how permissions are governed and distributed in both Access Manager versions, and how these flows differ.

Access Manager v2

A client will typically log in to a server application that first identifies the set of permissions associated with that client's user and later creates an authKey for it. The authKey and a defined permission set are sent to PubNub by the server in a grant call. PubNub stores the permissions mapping for the provided authKey in a database. Your client device passes this authKey during PubNub object initialization and retains it across multiple API calls. When the authKey expires and the client device attempts to log in again, it will have to request to be re-granted further access.

Access Manager v3

A client connects to the server application to initialize itself. That typically happens during a login attempt. Depending on your application logic, the client may present the permissions it needs, and your server will have a way of authenticating that this request is coming from an approved client. Alternatively, your client will be providing some type of identity request and your server will determine the appropriate permissions for that user. In either case, the server makes a grant request to PubNub to get a token with these permissions. In this grant request, the server defines how long these permissions should be valid. In turn, PubNub generates a time-limited, signed token with embedded permissions and returns the token to the server. The server passes this token back to the client device so it can communicate directly with PubNub. When the client device wants to change the permissions, the token is about to expire, or has been revoked, the client calls the server to request PubNub to grant a new token. Once the server receives a new one, it passes the token back to the client device.

Token size limits

There's a 32 KiB limit for the overall size of an HTTP request including a token. To avoid errors due to excessively large tokens in requests, set permissions with RegEx and use consistent naming conventions for your resources. See the channel naming convention for reference, or contact support for any questions.

Migration steps

To migrate from Access Manager v2 to v3:

1. Remove authKey from your client-side configuration and prepare the logic to set the token (which is returned by your server):

Node.js

1const pubnub = new PubNub({
2  subscribeKey: "mySubscribeKey",
3  publishKey: "myPublishKey",
4  userId: "myUniqueUserId"
5});
6

7pubnub.setToken("yourToken"); // Set the token returned by the server (see the next step for more details)

Python

1pn_config = PNConfiguration()
2pn_config.subscribe_key = "my_subscribe_key"
3pn_config.publish_key = "my_publish_key"
4pn_config.user_id = "my_unique_user_id"
5pubnub = PubNub(pn_config)
6

7pubnub.set_token("your_token") # Set the token returned by the server (see the next step for more details)

Java

1PNConfiguration.Builder configBuilder = PNConfiguration.builder(new UserId("yourUserId"), "yourSubscribeKey");
2configBuilder.publishKey("myPublishKey");
3PubNub pubNub = PubNub.create(configBuilder.build());
4

5pubNub.setToken("yourToken");
6// Set the token returned by the server (see the next step for more details)

Kotlin

1val pnConfiguration = PNConfiguration(UserId("myUserId")).apply {
2  subscribeKey = "my_subkey"
3  publishKey = "my_pubkey"
4  secure = true
5}
6val pubnub = PubNub.create(pnConfiguration)
7

8pubnub.setToken("yourToken"); // Set the token returned by the server (see the next step for more details)

Go

1pnconfig := pubnub.NewConfig()
2pnconfig.SubscribeKey = "MySubscribeKey"
3pnconfig.PublishKey = "MyPublishKey"
4pnconfig.SetUserId(UserId("myUniqueUserId"))
5pn := pubnub.NewPubNub(pnconfig)
6

7pn.SetToken("NewToken") // Set the token returned by the server (see the next step for more details)

C#

1PNConfiguration pnconfig = new PNConfiguration();
2pnconfig.SubscribeKey = "mySubscribeKey";
3pnconfig.PublishKey = "myPublishKey";
4pnconfig.UserId = "MyUniqueUserId";
5Pubnub pubnub = new Pubnub(pnconfig);
6

7pubnub.SetAuthToken("NewToken") // Set the token returned by the server (see the next step for more details)

Dart

1final myKeyset = Keyset(
2subscribeKey: 'mySubscribeKey',
3publishKey: 'myPublishKey',
4userId: UserId('yourUniqueUserId')
5);
6

7pubnub.setToken("yourToken") // The token is returned by the server in the next step

PHP

1use PubNub\PNConfiguration;
2$pnConfiguration = new PNConfiguration();
3$pnConfiguration->setSubscribeKey("MySubscribeKey");
4$pnConfiguration->setPublishKey("MyPublishKey");
5$pnConfiguration->setUuid("MyUniqueUuid");
6

7$pubnub->setToken("NewToken");

Ruby

1pubnub = Pubnub.new(
2    subscribe_key: 'my_subscribe_key',
3    publish_key: 'my_publish_key',
4    user_id: 'myUniqueUserId'
5);
6

7pubnub.set_token("newToken"); # Set the token returned by the server (see the next step for more details)

Tokens may need to be updated for various reasons. One reason could be because the user’s permissions have changed. Applications that securely authenticate client connections may allow clients to request changes to their own permissions. Other architectures may initiate changes on the server side and notify clients that they need a new token. Regardless of the approach, server logic should provide an interface that clients can call to request a new token.

Clients may also need to request a new token if it has (or will soon be) expired. Clients that make PubNub API requests with an expired token will get a 403 response.

Regardless of why a client has requested a new token, the server logic should make a new grant request and return the new token to the client. Once clients have the new token, they can set it in their PubNub object the same way they set a brand new token. Make sure not to create a new PubNub object on every token update, but rather set the token using the set_token() method (name may vary) available in your SDK.

For more information, refer to Manage Permissions with Access Manager.

1. Update your server-side code around grant APIs:

Node.js

1const pubnub = new PubNub({
2    subscribeKey: "mySubscribeKey",
3    publishKey: "myPublishKey",
4    secretKey: "mySecretKey",
5    userId: "myUniqueUserId"
6  });
7

8pubnub.grantToken(
9  {
10    ttl: 15,
11    authorized_uuid: "myAuthorizedUUID",
12    resources: {
13      channels: {
14        "myChannel": {
15          read: true  // False to disallow
16        }
17      }
18    }
19  }, function(status, token) {
20    console.log(token);
21  // Provide logic to return this token to your client
22  }
23);

show all 23 lines

Python

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

5pn_config = PNConfiguration()
6pn_config.subscribe_key = "my_subscribe_key"
7pn_config.publish_key = "my_publish_key"
8pn_config.secret_key = "my_secret_key"
9pn_config.user_id = "my_unique_user_id"
10pubnub = PubNub(pn_config)
11

12envelope = pubnub.grant_token() \
13    .ttl(60) \
14    .authorized_uuid('some_uuid') \
15    .channels([
16        Channel().id('some_channel_id').read().write().manage().delete().get().update().join(),
17        Channel().pattern('some_*').read().write().manage()
18    ]) \
19    .groups([
20        Group().id('some_group_id').read().manage(),
21        Group().pattern('some_*').read(),
22    ]) \
23    .uuids([
24        UUID().id('some_uuid').get().update().delete(),
25        UUID().pattern('some_*').get()
26    ]) \
27    .sync()
28

29token = envelope.result.token
30# Provide logic to return this token to your client

show all 30 lines

Java

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

7pubNub.grantToken()
8    .ttl(15)
9    .authorizedUUID("myAuthorizedUUID")
10    .channels(Arrays.asList(ChannelGrant.name("myChannel").read()
11    .async(result -> { /* check result */ });

Kotlin

1val pnConfiguration = PNConfiguration(UserId("myUserId")).apply {
2    subscribeKey = "my_subkey"
3    publishKey = "my_pubkey"
4    secretKey = "my_secretkey"
5    secure = true
6  }
7val pubnub = PubNub.create(pnConfiguration)
8pubnub.grantToken(
9    ttl = 15,
10    authorizedUUID = "my-authorized-uuid",
11    channels = listOf(ChannelGrant.name(name = "my-channel", read = true))
12).async { result ->
13        result.onFailure {
14            // Handle error
15        }.onSuccess {
16            // Handle result
17            // Provide logic to return this token to your client
18        }
19    }

show all 19 lines

Go

1pnconfig := pubnub.NewConfig()
2  pnconfig.SubscribeKey = "MySubscribeKey"
3  pnconfig.PublishKey = "MyPublishKey"
4  pnconfig.SecretKey = "MySecretKey"
5  pnconfig.SetUserId(UserId("myUniqueUserId"))
6  pn := pubnub.NewPubNub(pnconfig)
7

8pn := pubnub.NewPubNub(pnconfig)
9res, status, err := pn.GrantToken().
10        TTL(15).
11        AuthorizedUUID("my-authorized-uuid").
12        Channels(map[string]pubnub.ChannelPermissions{
13                "my_channel": {
14                        Read: true,
15                },
16        }).
17        Execute()
18

19// Provide logic to return this token to your client

show all 19 lines

C#

1PNConfiguration pnconfig = new PNConfiguration();
2pnconfig.SubscribeKey = "mySubscribeKey";
3pnconfig.PublishKey = "myPublishKey";
4pnconfig.SecretKey = "mySecretKey";
5pnconfig.UserId = "MyUniqueUserId";
6Pubnub pubnub = new Pubnub(pnconfig);
7

8PNResult<PNAccessManagerTokenResult> grantTokenResponse = await pubnub.GrantToken()
9  .TTL(15)
10  .AuthorizedUuid("my-authorized-uuid")
11  .Resources(new PNTokenResources()
12  {
13    Channels = new Dictionary<string, PNTokenAuthValues>() {
14                { "my-channel", new PNTokenAuthValues() { Read = true } } } // False to disallow
15  })
16  .ExecuteAsync();
17PNAccessManagerTokenResult grantTokenResult = grantTokenResponse.Result;
18PNStatus grantTokenStatus = grantTokenResponse.Status;
19// PNAccessManagerTokenResult is a parsed and abstracted response from the server
20if (!grantTokenStatus.Error && grantTokenResult != null)
21{
22    Console.WriteLine(pubnub.JsonPluggableLibrary.SerializeToJsonString(grantTokenResult));
23}
24else
25{
26    Console.WriteLine(pubnub.JsonPluggableLibrary.SerializeToJsonString(grantTokenStatus));
27}
28

29// Provide logic to return this token to your client

show all 29 lines

Dart

1final myKeyset = Keyset(
2  subscribeKey: 'mySubscribeKey',
3  publishKey: 'myPublishKey',
4  secretKey: 'mySecretKey',
5  userId: UserId('yourUniqueUserId')
6  );
7

8  // Prepare the request object
9  var request = pubnub.requestToken(ttl: 15, authorizedUUID: 'my-authorized-uuid');
10  request.add(ResourceType.channel, name: 'my-channel', read: true);
11

12  // Send the token request
13  var token = await pubnub.grantToken(request);
14  print('grant token = $token');
15

16  // Provide logic to return this token to your client

show all 16 lines

PHP

1use PubNub\PNConfiguration;
2$pnConfiguration = new PNConfiguration();
3$pnConfiguration->setSubscribeKey("MySubscribeKey");
4$pnConfiguration->setPublishKey("MyPublishKey");
5$pnConfiguration->setSecretKey("MySecretKey");
6$pnConfiguration->setUserId("MyUniqueUserId");
7

8$token = $pubnub->grantToken()
9    ->ttl(15)
10    ->authorizedUuid('my-authorized-uuid')
11    ->addChannelResources([
12        'my-channel' => ['read' => true, 'write' => true, 'update' => true],
13    ])
14    ->sync();
15);
16

17// Provide logic to return this token to your client

show all 17 lines

Ruby

1pubnub = Pubnub.new(
2    subscribe_key: 'my_subscribe_key',
3    publish_key: 'my_publish_key',
4    secret_key: 'my_secret_key',
5    user_id: 'myUniqueUserId'
6);
7

8pubnub.grant_token(
9    ttl: 15,
10    authorized_uuid: "my-authorized-uuid",
11    channels: {
12      "my-channel": Pubnub::Permissions.res(
13        read: true
14      )
15    }
16);
17

18# Provide logic to return this token to your client

show all 18 lines

Billing and pricing

Transactions in Access Manager v3 are counted in the same way as in v2, but you need to consider these changes and their effects:

1. In Access Manager v2, a developer has to make separate grant calls for the same client device. This means that you have to make separate grant calls if you want to grant different permissions for multiple resources (read to channel1 and write to channel2). In Access Manager v3, you can create multiple resource-permission mappings in a single call. This change can lower your monthly bill as you may observe some reduction in the overall number of transactions.

2. In Access Manager v3, using the default ttl of 1440 is best for most use cases. If your ttl in v2 was set for a longer period of time, migrating to Access Manager v3 would incur more grant calls and may impact your monthly bill.

3. In Access Manager v2, the authKey is a permissions identifier. These identifiable permissions are stored and replicated in PubNub's databases. In Access Manager v3, revoked tokens are stored on a denylist in the PubNub database. Typically, the storage space used by the v2 permissions is much bigger compared to the storage space used by the v3's denylist. However, database entries of both the v2 and v3 impact your storage capacity and are charged towards your monthly bill.

Access Manager v2

If you want to learn more about the previous version (v2) of Access Manager, refer to this feature description.