Access Manager v3 API: deprecated grantToken() scopes and parameters for JavaScript SDK

DeprecatedAccess Manager v3 is a current API. The uuids scope and the authorized_uuid parameter of grantToken() are deprecated, and the spaces scope is an older name for channels. New apps should use channels, users, and authorizedUserId. Go to Access Manager

This page documents the deprecated spaces and uuids scopes and the deprecated authorized_uuid parameter of grantToken() in the PubNub JavaScript SDK. Access Manager v3 is a current API, and only these ways of calling the method are deprecated. These ways of calling the method remain for apps that already use them. New apps grant tokens with the channels scope, the users scope, and authorizedUserId, described in Grant token.

• Grant token - spaces & users (deprecated) covers the spaces scope and the DataSync users scope.
• Deprecated authorized_uuid parameter covers the alias of authorizedUserId.
• Deprecated uuids scope covers App Context UUID metadata permissions.

Grant token - spaces & users (deprecated)

Not recommended

Granting tokens with the spaces scope is an older way to name channels, and the SDK does not mark it deprecated. Use the channels scope of grantToken() instead.

Requires Access Manager add-on

This method requires that the Access Manager add-on is enabled for your key in the Admin Portal. See Enable the features your app calls.

Requires Secret Key authentication

Granting permissions to resources should be done by administrators whose SDK instance has been initialized with a Secret Key (available on the Admin Portal on your app's keyset).

The secret key grants privileged access to your PubNub application. It must remain on a trusted server and must never be included in client applications.

The grantToken() method generates a time-limited authorization token with an embedded access control list. The token defines time to live (ttl), authorizedUserId, and a set of permissions giving access to one or more resources:

• spaces
• users

The spaces scope maps to the channels scope. The users scope holds DataSync User permissions, keyed by user ID. In earlier SDK versions, users held App Context UUID metadata permissions. Those permissions now use the deprecated uuids scope.

When you parse the token with parseToken(), spaces appears under channels, users stays under users, and uuids stays under uuids. The samples below are JavaScript. The TypeScript types of grantToken() do not include spaces, so in a TypeScript project the call fails to compile, although the SDK accepts it at runtime. Use channels to stay within the types.

A token that names an authorized user ID works only for that user ID, with the permissions that it defines. A request that the token does not authorize fails with a 403 status and an error message.

Permissions

The grant request allows your server to securely grant your clients access to the resources within the PubNub Platform. There is a limited set of operations the clients can perform on every resource:

Resource	Permissions
space	read, write, get, manage, update, join, delete
user	create, get, update, delete

For permissions and API operations mapping, refer to Manage Permissions with Access Manager v3.

TTL

The ttl (time to live) parameter defines how many minutes the permissions remain valid. After expiration, the client must get a new token to maintain access. Every Access Manager token requires a ttl in minutes, and there is no default. An Access Manager token's ttl ranges from 1 minute to 43,200 minutes (30 days).

Recommended ttl value

For security reasons, it's recommended to set ttl between 10 and 60, and create a new token before this ttl elapses.

For more details, see TTL in Access Manager v3.

RegEx

If you prefer to specify permissions by setting patterns, rather than listing all resources one by one, you can use regular expressions. To do this, set RegEx permissions as patterns before making a grant request.

For more details, see RegEx in Access Manager v3.

Authorized user ID

Setting an authorizedUserId in the token specifies which client device uses this token in every request to PubNub. PubNub then authorizes every request before it processes the request. If you don't specify authorizedUserId in the grant request, any client with any userId can use the token. Restrict tokens to a single authorizedUserId to prevent impersonation.

For how the binding works and what it protects against, see Authorized UUID in Access Manager v3.

Method(s)

1pubnub.grantToken({
2    ttl: number,
3    authorizedUserId?: string,
4    resources?: object,
5    patterns?: object,
6    meta?: object
7}): Promise<string>;

* required

ttl* required#

type: Type: number

Default: no default

Total number of minutes for which the token is valid. An Access Manager token's ttl ranges from 1 minute to 43,200 minutes (30 days).

authorizedUserId#

type: Type: string

Default: no default

Single user ID that is authorized to use the token to make API requests to PubNub. Without it, any client with any user ID can use the token.

resources#

type: Type: object

Default: no default

Object containing resource permissions.

property of resources: users#

type: Type: object

Default: no default

Object containing user permissions. For example: {"userId-1": {get: true, update: true, delete: true},"userId-2": {...}}.

property of resources: spaces#

type: Type: object

Default: no default

Object containing space permissions. For example: {"space-id-1": {read: true, write: true, manage: true, delete: true, get: true, update: true, join: true},"space-id-2": {...}}.

patterns#

type: Type: object

Default: no default

Object containing permissions to multiple resources specified by a RegEx pattern.

property of patterns: users#

type: Type: object

Default: no default

Object containing user permissions to apply to all users matching the RegEx pattern. For example: {"userId-pattern-1": {get: true, update: true, delete: true},"userId-pattern-2": {...}}.

property of patterns: spaces#

type: Type: object

Default: no default

Object containing space permissions to apply to all spaces matching the RegEx pattern. For example: {"space-pattern-1": {read: true, write: true, manage: true, delete: true, get: true, update: true, join: true}, "space-pattern-2": {...}}.

meta#

type: Type: object

Default: no default

Extra metadata that the token carries. Values must be scalar. Arrays and objects are not supported.

A grant must include a permission for at least one user or space, either under resources or under patterns. A grant that includes none fails validation with the message Missing values for either Resources or Patterns.

Sample code

1

Returns

This method returns a promise that resolves with the token as a string and rejects with a PubNubError. The error carries a status object with category and statusCode, and status.errorData holds the details that PubNub returned for a failed request. This method also takes a callback as the second argument, and with a callback the method returns nothing and PubNub calls it with (status, response). On success, status.error is false and status.operation names the operation, and on failure status.error is true and response is null. All examples use async/await, so wrap a call in try...catch to receive the error status.

1"p0thisAkFl043rhDdHRsCkNyZXisRGNoYW6hanNlY3JldAFDZ3Jwsample3KgQ3NwY6BDcGF0pERjaGFuoENnctokenVzcqBDc3BjoERtZXRhoENzaWdYIGOAeTyWGJI"

Other examples

Grant an authorized client different levels of access to various resources in a single call

The code below grants my-authorized-userId:

• Read access to space-a, and get to userId-c.
• Read/write access to space-b, space-c, space-d, and get/update to userId-d.

1

Grant an authorized client read access to multiple channels using RegEx

The code below grants my-authorized-userId read access to all channels that match the space-[A-Za-z0-9] RegEx pattern.

1

Grant an authorized client different levels of access to various resources and read access to channels using RegEx in a single call

The code below grants the my-authorized-userId:

• Read access to space-a and userId-c.
• Read/write access to space-b, space-c, space-d, and get/update to userId-d.
• Read access to all channels that match the space-[A-Za-z0-9] RegEx pattern.

1

Error responses

If you submit an invalid request, the server returns HTTP 400 with a message that identifies the missing or incorrect argument. Causes can include a RegEx issue, an invalid timestamp, or incorrect permissions. The server returns the details of the error in the JSON format.

Deprecated authorized_uuid parameter

Deprecated

authorized_uuid is deprecated. Use authorizedUserId instead.

authorized_uuid is an alias of authorizedUserId. Both name the client that is allowed to use the token, and the call can't combine the two.

1pubnub.grantToken({
2    ttl: number,
3    authorized_uuid?: string,
4    resources?: object,
5    patterns?: object,
6    meta?: object
7}): Promise<string>;

authorized_uuid#

type: Type: string

Default: no default

Alias of authorizedUserId. The call can't combine the two.

Replacement

authorizedUserId

For how the binding works and what it protects against, see Authorized UUID in Access Manager v3. The current parameter is described in Grant token.

Deprecated uuids scope

Deprecated

The uuids scope is deprecated. To grant access to DataSync User objects, use the users scope.

The uuids scope holds App Context UUID metadata permissions, such as names or avatars. DataSync checks the users scope, while App Context checks uuids. A grant under uuids does not authorize DataSync user operations.

Resource	Permissions
uuids	get, update, delete

resources.uuids#

type: Type: object

Default: no default

App Context UUID metadata permissions, for example: {"uuid-1": {get: true, update: true, delete: true},"uuid-2": {...}}.

Replacement

resources.users (DataSync User objects only)

patterns.uuids#

type: Type: object

Default: no default

App Context UUID metadata permissions for matching IDs, for example: {"uuid-pattern-1": {get: true, update: true, delete: true},"uuid-pattern-2": {...}}.

Replacement

patterns.users (DataSync User objects only)

The SDK accepts only one of users and uuids in a single grantToken() call. The check spans the whole request, so resources.users cannot be combined with patterns.uuids. Mixing them fails validation before anything is sent. This differs from channels and spaces, which name the same channel scope, and from authorizedUserId and authorized_uuid, which name the same client.

Everything else combines freely. Use uuids only for App Context UUID metadata permissions.