On this page

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

Access Manager is an optional add-on that lets you control who can read from or write to your PubNub channels and user metadata. Without it, any client with your keys has unrestricted access to all resources on that keyset.

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.

DataSync extends the same tokens with resource types of its own, so one grant can cover messaging, App Context metadata, and DataSync objects together. Refer to DataSync access control.

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.

Access Manager is optional but recommended

Access Manager is an optional add-on you enable per keyset in the Admin Portal. It's not enabled by default.

Without Access Manager, PubNub resources on this keyset have no access controls. Any client that connects can reach channels and metadata without permission checks — including Publish, Subscribe, Presence, and all other PubNub operations.

Enable Access Manager when your app requires:

  • Private or restricted channels, such as 1:1 chat, group DMs, or member-only spaces.
  • User-scoped permissions, to bind tokens to a specific User ID so only that user can consume them.
  • Sensitive data handling, any channel carrying personal, financial, or health information.
  • Regulatory compliance, HIPAA, SOC 2, GDPR, or similar requirements that mandate access control.

If your app streams public, non-sensitive data with no user authentication (for example, a live sports scoreboard), you may not need Access Manager. For all other production scenarios, enabling it is strongly recommended.

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.

Access Manager in Admin Portal

OptionDescription
Revoke v3 Token
Invalidate a token so it can’t authenticate access to PubNub resources.
Verify Access Manager status programmatically

To check whether Access Manager is enabled for a keyset:

  • Make a Publish, Subscribe, or History call without a secret key or auth token. A 403 response means Access Manager is enabled; a successful response means it is not.
  • Query the Admin Portal REST API and check whether uls is true in the keyset configuration.

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:

Client Devices → Your Server → PN Network ← Client Devices

  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.

The following operations require the secretKey and must only be called from your server:

  • grantToken() — issue a v3 access token with embedded permissions
  • revokeToken() — add a token to the deny list

Your trusted backend server can also use the secretKey directly for standard operations such as Publish. Never expose the secretKey to clients — clients must always use tokens issued by your server via grantToken(). Clients do not call grantToken() themselves.

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.

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

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 (uuids), which are other users' App Context metadata, such as their names or avatars
  • Users (users), which are DataSync User objects
  • DataSync entities, relationships, and memberships

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

note
Use users for DataSync, uuids for App Context

users and uuids both take a User ID, but they are separate scopes that different products read. Grant users for DataSync User objects. Grant uuids for App Context user metadata, which is what the examples on this page use. A token that grants only uuids does not authorize DataSync operations on the matching user.

A single grant carries one name from the pair, never both. The check spans the whole request, so resources.users can't be paired with patterns.uuids either. authorizedUserId and authorized_uuid pair up the same way.

For the DataSync scopes and the field-level projections that go with them, refer to Grant DataSync permissions below.

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.
1pubnub.grantToken(
2    {
3        ttl: 15,
4        authorized_uuid: "my-authorized-uuid",
5        resources: {
6            channels: {
7                "channel-a": {
8                    read: true
9                },
10               "channel-b": {
11                    read: true,
12                    write: true
13                },
14               "channel-c": {
15                    read: true,
show all 48 lines

Grant DataSync permissions​

DataSync grants go through the same grantToken call. You add the users scope for DataSync User objects, a dataSync scope for entities, relationships, and memberships, and an optional dataSyncProjections map that narrows a grant down to individual payload fields.

Both tabs below are JavaScript and grant the same two user records, so you can read the scope names side by side. The App Context tab is the shape the examples earlier on this page use. The DataSync tab swaps uuids for users, then adds the scopes that have no App Context equivalent.

Grants get on two DataSync users, get and update on one entity, get on every entity matching the product-.* pattern, membership create, get, and delete, and reads and writes limited to the admin projection on product-sneaker-42.

1pubnub.grantToken({
2    ttl: 15,
3    authorizedUserId: "my-authorized-user",
4    resources: {
5        users: {
6            "user-c": {
7                get: true
8            },
9            "user-d": {
10                get: true,
11                update: true
12            }
13        },
14        dataSync: {
15            entities: {
show all 46 lines

The scopes a DataSync grant can carry:

Grant scopeCoversPermissions
users
DataSync User objects
create, get, update, delete
channels
DataSync Channel objects, alongside the messaging permissions on that channel
the channel permissions listed under Permissions
dataSync.entities
Entities of the classes you define
create, get, update, delete
dataSync.relationships
Relationships of the classes you define
create, get, update, delete
dataSync.memberships
Memberships linking a channel to a user
create, get, update, delete
dataSyncProjections
Which payload fields the token reads and writes on a given object
a single projection name per id or pattern

DataSync permissions follow the grant's top-level split: put exact IDs under resources.dataSync and RegEx patterns under patterns.dataSync. dataSyncProjections has its own nested resources and patterns maps for projection assignments. For projections, an exact ID assignment wins over a pattern match.

Tokens don't select event projection channels

DataSync filters each event payload according to the class projection associated with its delivery channel: the object ID channel carries the __default__ view, while __<projection>__<id> carries the named projection's view. A token's dataSyncProjections entry controls API reads and writes, but it doesn't automatically select or authorize an event channel. Control who receives each view with an ordinary channel read grant on that channel. Refer to Projections and events.

For the resource-type mapping, the error codes, and the service limits, refer to DataSync access control.

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.

Pattern matching for patterns is evaluated on the PubNub server (not by the SDK). Supported syntax is based on RE2: backreferences and lookaround assertions are not supported.

Common wildcard-style patterns using RE2:

GoalRE2 patternExample match
All channels with a prefix
chat-.*
chat-general, chat-team-eng
All channels with a suffix
.*-public$
room-public, lobby-public
Numeric identifiers
^room-[0-9]+$
room-1, room-42
All channels
.*
any channel name
Difference from Access Manager v2

Access Manager v2 wildcards only matched one dot-level deep — a.* matched a.general but not a.team.eng. RE2 patterns in v3 match the full channel name string, giving you full flexibility. See the migration guide for a full comparison.

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.

Manage the User IDs that tokens authorize
Per-device access control

To restrict access to a single device, combine authorized_uuid with a device-specific channel name (for example, device-{uuid}). The authorized_uuid ensures the token cannot be reused by another client. The device-specific channel ensures only messages published to that channel reach the device. PubNub does not filter published messages by subscriber — access control is enforced at the subscribe layer.

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.
1const token = await pubnub.revokeToken("p0AkFl043rhDdHRsple3KgQ3NwY6BDcENnctokenVzcqBDczaWdYIGOAeTyWGJI");

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:

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

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:

1pubnub.parseToken("yourToken")

See a sample response:

1{
2   "version":2,
3   "timestamp":1629394579,
4   "ttl":15,
5   "authorized_uuid": "user1",
6   "resources":{
7      "uuids":{
8         "user1":{
9            "read":false,
10            "write":false,
11            "manage":false,
12            "delete":false,
13            "get":true,
14            "update":true,
15            "join":false
show all 76 lines
DataSync scopes in a decoded token

The response above is a token granted for channels, channel groups, and uuids. A token that also carries users or DataSync permissions decodes them under resources.users and resources.dataSync, with its projections under meta on the pn-projections key. Each of those keys appears only when the grant actually set it, so guard the access when you read one.

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:

Client Devices → Your Server → PN Network ← Client Devices

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.

1pubnub.setToken("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.

The following example illustrates strategy 2 — a client-side timer that proactively requests a new token before expiry:

1function scheduleTokenRefresh(token) {
2  const { timestamp, ttl } = pubnub.parseToken(token);
3

4  // ttl is in minutes; timestamp is Unix seconds
5  const ttlMs     = ttl * 60 * 1000;
6  const refreshAt = ttlMs * 0.8;  // refresh at 80% of TTL elapsed
7

8  setTimeout(async () => {
9    const newToken = await fetchTokenFromYourServer();
10    pubnub.setToken(newToken);
11    scheduleTokenRefresh(newToken); // reschedule for the new token
12  }, refreshAt);
13}
14

15// Call once after the client receives its initial token
show all 16 lines

Adapt fetchTokenFromYourServer() to your server's token API. Apply exponential backoff if the server is temporarily unavailable.

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:

ResourceAvailable Permissions
Channel
read, write, delete, get, update, manage, join
Channel Group
read, manage
UUID Metadata
get, update, delete
Users
create, get, update, delete
DataSync Entities
create, get, update, delete
DataSync Relationships
create, get, update, delete
DataSync Memberships
create, get, update, delete
Scope permissions to channels and channel groups

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 OperationResourcePermission
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
Understand the operations behind Pub/Sub permissions

Presence​

PubNub OperationResourcePermission
Here Now
Channel
Read
Where Now
Channel
None required
Get State
Channel
Read
Set State
Channel
Read
Understand the operations behind Presence permissions
Using hereNow() with Access Manager v3

Grant read on the channel server-side, then call hereNow() client-side:

1// Server: issue a token with read on the target channel
2const token = await pubnub.grantToken({
3  ttl: 60,
4  authorized_uuid: "client-uuid",
5  resources: { channels: { "lobby": { read: true } } }
6});
7

8// Client: set the token, then call hereNow
9pubnub.setToken(token);
10const result = await pubnub.hereNow({ channels: ["lobby"] });

To use hereNow() across multiple channels, include each channel in resources, or use a pattern such as lobby-.*.

Message Persistence​

PubNub OperationResourcePermission
History - Fetch Messages
Channel
Read
Message Counts
Channel
Read
Delete Messages
Channel
Delete
Understand the operations behind Message Persistence permissions

File sharing​

PubNub OperationResourcePermission
Send file on channel
Channel
Write
List files
Channel
Read
Download file
Channel
Read
Delete file
Channel
Delete
Understand the operations behind File sharing permissions

Channel groups​

PubNub OperationResourcePermission
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
Apply channel group permissions to subscription management

App Context​

PubNub OperationResourcePermission
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
Understand the operations behind App Context permissions

DataSync​

PubNub OperationResourcePermission
Create DataSync user
Users
Create
Get or list DataSync users
Users
Get
Replace or patch DataSync user
Users
Update
Delete DataSync user
Users
Delete
Get or list DataSync channels
Channel
Get
Replace or patch DataSync channel
Channel
Update
Delete DataSync channel
Channel
Delete
Create DataSync entity
DataSync Entities
Create
Get or list DataSync entities
DataSync Entities
Get
Replace or patch DataSync entity
DataSync Entities
Update
Delete DataSync entity
DataSync Entities
Delete
Create relationship or membership
DataSync Relationships, DataSync Memberships
Create
Get or list relationships or memberships
DataSync Relationships, DataSync Memberships
Get
Replace or patch relationship or membership
DataSync Relationships, DataSync Memberships
Update
Delete relationship or membership
DataSync Relationships, DataSync Memberships
Delete
Subscribe to a DataSync object's events
Channel
Read
Subscribe to a projection's events
Channel (__<projection>__<id>)
Read

DataSync channel objects authorize against the channels resource rather than a dataSync scope, the same resource that gates messaging on that channel. Note that reading one is get, not read: read on a channel governs subscribing, which is how you receive that object's events. Refer to DataSync access control for the full resource-type mapping, and to Projections for field-level access.

Understand the operations behind DataSync permissions

Mobile Push Notifications​

PubNub OperationResourcePermission
Register channel for push
Channel
Read
Remove channel's push registration
Channel
Read
Understand the operations behind Mobile Push permissions

Message Actions​

PubNub OperationResourcePermission
Add Message Action
Channel
Write
Remove Message Action
Channel
Delete
Get Message Actions
Channel
Read
Get History with Actions
Channel
Read
Last updated on
Related Resources
On this page