Permissions

When you develop a chat app, you might want to set rules that let only selected users access specific channels and user metadata. You can set up a detailed permission schema for your application and decide who can do what with your data. This way, you secure and protect your application against unauthorized third-party access attempts.

For example, you can let only specific users modify public channel information or profiles of other chat users. You can also let only admins remove users from channels for offensive behavior.

Chat SDK, as a purely client-side library, doesn't do anything specific to handle such permissions internally, apart from imposing some limits through client-side errors:

  • The allowed channel membership (direct, group, or public channel types).
  • Availability of specific features in public chats (you'll get errors when implementing such Chat SDK features as typing indicator, invites, or read receipts).

Still, you can use the cryptographic, token-based permission administrator from PubNub called Access Manager to impose strict access rules for PubNub resources in your app.

Chat SDK is based on the JavaScript SDK, and you can easily access all methods the JavaScript SDK exposes. The same applies to all the Access Manager-related methods.

Required configuration

Before you start using Access Manager, you must configure your app:

  1. Enable Access Manager on your app's keyset in the Admin Portal.
  2. Initialize the Chat SDK (init()):
  • With the secretKey on your servers to secure your PubNub instance. secretKey is a shared secret between your application's server and PubNub and it's used to administer Access Manager permissions for your client applications by signing and verifying the authenticity of messages and requests. Read Moderation for examples.

  • With the authKey on your clients to authenticate users in your application and grant them access to PubNub resources (other users' metadata and channels). Read Moderation for examples.

Secret key security

The secretKey should only be used within a secure server and never exposed to client devices. If the secretKey is ever compromised, it can be an extreme security risk to your application. If you suspect your secretKey has been compromised, you can generate a new secretKey for the existing PubNub keyset on the Admin Portal.

Use Access Manager

To implement access rules in your app, refer to Access Manager API using these JavaScript SDK methods:

  • chat.sdk.grantToken() to generate a time-limited authorization token with an embedded access control list.

    Channel group limitation

    Chat SDK doesn't support channel groups, so you can only set permissions for the channels and users.

  • chat.sdk.revokeToken() to disable an existing token and revoke all permissions embedded within.

  • chat.sdk.parseToken() to decode an existing token and return the object containing permissions embedded in that token.

  • chat.sdk.setToken() to update the authentication token granted by the server.

Resource permissions

You can use Access Manager in Chat SDK to define what operations (like read, write, or get) your chat app users can do with such PubNub resources as channels (channels) and other users' metadata (uuids):

Resource typePermissions
channelsread, write, get, manage, update, join, delete
uuidsget, update, delete

Read the Moderation docuemntation to learn how you can mute and ban users in your chat app and secure these restrictions with Access Manager.

Example

Grant support-agent the read type of access to a group channel called priority-tickets and write type of access to all public channels. Granted access must expire after 15 minutes.

try {
const token = await chat.sdk.grantToken({
ttl: 15,
authorized_uuid: "support-agent",
resources: {
channels: {
"priority-tickets": {
read: true
},
},
},
patterns: {
channels: {
// wildcard pattern that refers to all channels whose IDs start with the "public" prefix
"public.*": {
show all 23 lines

Operations-to-permissions mapping

The type of access level you grant on a given resource type defines which operations users can perform in your app. For example, write access given to a user for the channels resource type (either specific channels or channel patterns) lets them send messages to this channel/these channels (calling the PubNub Pub/Sub API underneath and the Chat SDK's sendText() method).

The following tables show how specific permissions granted to PubNub resources translate to operations users can later perform in a chat app.

Pub/Sub

PubNub operationResource type(s)PermissionChat SDK method(s)
Publish on channelschannelswriteSend text messages (sendText())

Send messages with referenced channels and user mentions (send())

Forward messages (forward(), forwardMessage())

Create and send events (emitEvent())

Report users/messages (report())
Send signals to channelschannelswriteTyping indicator methods

Create and send events (emitEvent())
Subscribe to channelschannelsreadTyping indicator methods

Receive events (listenForEvents())

Receive messages (connect())

Membership updates (streamUpdates(), streamUpdatesOn())

Channel updates (update(), updateChannel())

Messages updates (streamUpdates(), streamUpdatesOn())

User updates (streamUpdates(), streamUpdatesOn())
Subscribe to presence channelsPresence channels (<channel-name>-pnpres)readn/a
Unsubscribe from channelschannelsNone requiredStop receiving typing signals, events, messages, updates on membership, channels, messages, and users

Presence

PubNub operationResource type(s)PermissionChat SDK method(s)
Here NowchannelsreadChannel presence (whoIsPresent())
Where NowchannelsNone requiredChannel presence (wherePresent(), isPresentOn(), isPresent())

Message Persistence

PubNub operationResource type(s)PermissionChat SDK method(s)
Fetch historical messageschannelsreadgetHistory()
Message countschannelsreadUnread messages (getUnreadMessagesCount(), getUnreadMessagesCounts())
Delete messageschannelsdeletedelete()

File Sharing

PubNub operationResource type(s)PermissionChat SDK method(s)
Send files on channelschannelswritesendText()
List fileschannelsreadgetFiles()
Delete fileschannelsdeletedeleteFile()

App Context

PubNub operationResource type(s)PermissionChat SDK method(s)
Set user metadatauuidsupdateCreate users (createUser())

Update user metadata (update(), updateUser())
Delete user metadatauuidsdeletedeleteUser(), delete()
Get user metadatauuidsget

For channel references to work with Access Manager enabled on your app's keyset, make sure the Disallow Get All Channel Metadata option for App Context on the Admin Portal is not selected.
Get user data (getUser())

Track mentions and channel references (onChange())
Get all user metadatauuidsGranted by default by enabling App Context on the app's keyset on the Admin Portal. The Disallow Get All User Metadata option disables it.chat.getUsers()
Set channel metadatachannels

When working with threads, also grant permissions to PUBNUB_INTERNAL_THREAD channels.
update, getCreate channels (createDirectConversation(), createGroupConversation(), createPublicConversation())

Update channels (update(), updateChannel())

Pin messages (pin(), pinMessage())

Threads (createThread(), pinMessage(), pinMessageToParentChannel(), pinToParentChannel(), unpinMessage(), unpinMessageFromParentChannel(), unpinFromParentChannel())
Delete channel metadatachannelsdeletedelete(), deleteChannel()
Get channel metadatachannelsgetGet channel details (getChannel())

Get pinned messages (getPinnedMessage())

Get thread (getThread())
Get all channel metadatachannelsGranted by default by enabling App Context on the app's keyset on the Admin Portal. The Disallow Get All Channel Metadata option disables it.chat.getChannels()
Set channel memberschannelsmanageInvite multiple users to channels (inviteMultiple())

Mute/Ban users (setRestrictions())
Remove channel memberschannelsmanageUnmute/Unban users (setRestrictions())
Get channel memberschannelsgetGet members (getMembers())

Check restrictions (getUserRestrictions(), getUsersRestrictions(), getChannelsRestrictions(), getChannelRestrictions())
Set channel membershipschannels, uuidsjoin on channels
update on uuids
Create channels (createDirectConversation(), createGroupConversation())

Invite a user to a channel (invite())

Join channels (join())

Update membership (update())

Unread messages (setLastReadMessage(), markAllMessagesAsRead())
Remove channel membershipschannels, uuidsjoin on channels
update on uuids
Leave channels (leave())
Get channel membershipsuuidsgetList channels (getChannels()), getMemberships()

Mobile Push Notifications

PubNub operationResource type(s)PermissionChat SDK method(s)
Register channel for pushchannelsreadregisterForPush(), registerPushChannels()
Remove channel's push registrationchannelsreadunregisterFromPush(), unregisterPushChannels()

Message Reactions

PubNub operationResource type(s)PermissionChat SDK method(s)
Add message reactionchannelswritetoggleReaction()
Remove message reactionchannelsdeletetoggleReaction()
Get history with reactionschannelsreadgetHistory()
Last updated on