Migrate from Access Manager v2 to v3

Showing JavaScript examples.

Access Manager v2 relies on an authKey your server assigns, granted through a separate grant() call for each permission set. Access Manager v3 replaces both of those with a signed token your server requests through grantToken() and sets on the client with a single setToken() call. This guide moves an existing v2 integration to v3.

Access Manager v2 still works. The reason to move is the per-request cost: v2 stores every permission mapping in a server-side database and checks it on every request. A v3 token carries its own permissions, so PubNub checks it instantly instead.

Before you start

Confirm you have:

• Access Manager enabled on your keyset. See Configure access control.
• A server-side PubNub instance already initialized with a secretKey, since that's what both grant() and grantToken() require. See Initialize a server SDK with a secret key.
• An existing v2 integration: clients that set an authKey at initialization, and a server that calls grant().

Migrate with an AI coding assistant

If you use an AI coding assistant, paste this prompt into it to run the migration. The prompt makes the assistant read this guide, list every grant() call and authKey first, and change the server before any client. It also makes the assistant stop before it removes authKey from a client or removes a v2 grant() call.

Migrate this codebase from PubNub Access Manager v2 to Access Manager v3.


1. Read the migration guide first:
   https://www.pubnub.com/docs/migration-guides/access-manager-v3.md
   If the PubNub MCP server is connected, you can call get_general_migration_guide
   instead. Where the guide and your own knowledge of PubNub SDKs disagree,
   follow the guide and tell me.
2. Before you edit anything, list every server-side grant() call, every client
   that sets authKey, and the code path that hands the auth key to each client.
   Tell me which clients are not in this repository. Then show me a plan and wait
   for my approval.
3. Change the server first. Replace grant() with grantToken(), and combine every
   permission set for the same client into one grantToken() call. Keep the
   existing arguments and change only the method and the resource structure.
   Return the token to the client where the auth key used to go.
4. Keep each grantToken() request within the request-size limit in the guide.
   Where a grant lists many resources by name, use an RE2 pattern instead, and
   tell me if our resource names don't fit a pattern.
5. STOP before you change any client. Ask me to confirm that the server change
   is deployed and returns tokens.
6. On each client, remove authKey from the configuration and set the token from
   the server with the SDK's setToken method. To refresh a token, call setToken
   again instead of recreating the client.
7. STOP before you remove any v2 grant() call. Clients that still set authKey
   depend on it, so keep it until I confirm those clients are retired.
8. grant() and grantToken() need the secret key, so they run on the server only.
   Never put the PubNub secret key in client code, and never commit keys or
   tokens.
9. Make one small change at a time. After each change, run the build and tests
   and show me the output.
10. When you finish, list every file you changed and the steps left for me.

show all 31 lines

How the authorization flow changes

Both versions involve the same three actors: your client, your server, and PubNub. The difference is what moves between them, and what PubNub checks on every call.

Access Manager v2 stores the authKey-to-permissions mapping in a database on PubNub's servers, so every authenticated request costs a database lookup. The v2 flow runs in six steps:

1. The client sends a login request to your server.
2. Your server calls grant() with an authKey, using the secretKey.
3. PubNub stores the authKey-to-permissions mapping and acknowledges.
4. Your server returns the authKey to the client.
5. The client sets the authKey in the SDK and makes API calls with it.
6. On each call, PubNub looks up the permissions for that authKey in its database and allows or rejects the request.

Access Manager v3 embeds the permissions inside a signed token, so PubNub checks the signature instead of looking anything up. Once the client has the token, its calls carry no extra round trip. The v3 flow runs in six steps:

1. The client sends a login request to your server.
2. Your server calls grantToken() using the secretKey.
3. PubNub returns a signed, time-limited token to your server.
4. Your server returns the token to the client.
5. The client sets the token with setToken() and makes API calls with it.
6. On each call, PubNub validates the token signature and permissions, with no database lookup, and allows or rejects the request.

Update your client configuration

Remove authKey from client-side configuration, and set the token your server returns using setToken (the method name varies slightly by SDK) instead.

• JavaScript
• Python
• Java
• Kotlin
• Go
• C#
• Dart
• PHP
• Ruby

Before, with a v2 authKey:

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

After, with a v3 token:

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

7pubnub.setToken("yourToken"); // Token returned by your server's grantToken call

If you need to update the token again later, without recreating the client, call the same setToken-family method again. Refer to Initialize a client SDK with an auth key for the full procedure, including every SDK's method name.

Update your server's grant calls

Replace each grant() call with a grantToken() call. In v2, granting different permissions to different resources for the same client needs one grant() call per permission set. In v3, grantToken() accepts every resource-permission mapping in a single call, so the equivalent grant collapses into one request.

The examples below show a v2 grant() that gives read access to channel-a, channel-group-b, and uuid-c. Giving read and write to channel-b, channel-c, and channel-d at the same time needs a second grant() call with the same shape, since v2 applies one permission set per call. The v3 grantToken() example grants both permission sets, plus a RE2 pattern, in the single call.

• JavaScript
• Python
• Java
• Kotlin
• Go
• C#
• Dart
• PHP
• Ruby

Before, a v2 grant limited to one permission set:

1pubnub.grant(
2  {
3    channels: ["channel-a"],
4    channelGroups: ["channel-group-b"],
5    uuids: ["uuid-c"],
6    authKeys: ["my-authorized-key"],
7    ttl: 15,
8    read: true
9  },
10  function (status) {
11    console.log(status);
12  }
13);

After, a v3 token covering multiple permission sets in one call:

1pubnub.grantToken(
2    {
3        ttl: 15,
4        authorized_uuid: "my-authorized-uuid",
5        resources: {
6            channels: {
7                "channel-a": { read: true },
8                "channel-b": { read: true, write: true },
9                "channel-c": { read: true, write: true },
10                "channel-d": { read: true, write: true }
11            },
12            groups: {
13                "channel-group-b": { read: true }
14            },
15            uuids: {
16                "uuid-c": { get: true },
17                "uuid-d": { get: true, update: true }
18            }
19        },
20        patterns: {
21            channels: {
22                "^channel-[A-Za-z0-9]$": { read: true }
23            }
24        }
25    },
26    function (status, token) {
27        console.log(token)
28    });

show all 28 lines

Your own v2 integration's exact call shape may differ slightly from the examples above. Keep your existing arguments and swap only the method and resource structure. For the full grant and revoke procedure, including RE2 pattern syntax, refer to Grant, change, and revoke permissions.

Keep token grants within the request-size limit

Access Manager grantToken() requests over 32 KiB return HTTP 414 (URI Too Long).

A token that lists many individual resources by name can make the grantToken() request exceed the limit. A v2 integration that already grants many separate channels is the most likely to cross it after combining those grants into fewer, larger v3 calls.

Use an RE2 pattern instead of listing every resource. Keep a consistent naming convention for your channels, channel groups, and User IDs, so one pattern can cover many of them. Refer to Grant, change, and revoke permissions for RE2 pattern syntax, or contact support if your resource names can't be made to fit a pattern.

What changes on your bill

Access Manager v3 counts transactions the same way v2 does. This migration changes only the number of grant calls. Access Manager v2 needs a separate grant() call for each distinct permission set on a client. Access Manager v3's grantToken() combines every resource-permission mapping for that client into one call. If your integration currently makes several grant() calls per client, combining them into one grantToken() call reduces the number of grant transactions your server makes for that client.

Related tasks

• Access Manager. The v3 authorization flow, resources, and token model.
• Grant, change, and revoke permissions. Issue, change, and revoke tokens from your server.
• Initialize a client SDK with an auth key. Set a token on the client at startup or after a refresh.
• Permission model. Every permission flag available on each resource type.
• Available migration guides. Every migration guide in the current documentation.