Grant token

Returns a signed token that can be used to access the requested resources for a specific duration.

Path Parameters
sub_key string — REQUIRED

Your app's subscribe key from Admin Portal.

Query Parameters
timestamp integer — REQUIRED

Unix epoch timestamp used as a nonce for signature computation. Must have no more than ± 60 second offset from NTP. This is not associated with the TTL at all.

Example: 1607457300

signature string — REQUIRED

Used to verify the request was signed with the secret key associated with the subscribe key. For information on how to compute the signature, refer to Signature generation.

Example: v2.k80LsDMD-sImA8rCBj-ntRKhZ8mSjHY8Ivngt9W3Yc4

uuid string

A UTF-8 encoded string of up to 64 characters used to identify the client.

Example: myUniqueUserId

Request Body — REQUIRED

The request body takes the form of a JSON object containing ttl that defines the token lifetime (in minutes) and the permissions object that maps resources to permission rules. It may also contain arbitrary application metadata (meta). Permissions can be listed in a sequence (resources) and/or specified as regular expressions patterns. The permissions object must contain at least one of resources or patterns properties, meaning at least one of channels, groups, users, spaces, or uuids objects in resources or patterns must be non-empty. It can also contain meta. Additionally, the permissions object may contain the uuid property (string) to designate the uuid that will be solely authorized to use the granted token.

Parameter Type Description

ttl Int The total number of minutes for which the token will remain valid. The minimum allowed ttl is 1 minute. The maximum allowed ttl is 43200 (30 days). This parameter is required and there is no default for it. Once the ttl expires, the read and write attributes are immediately set to false.
permissions.resources.channels Object A mapping of channel names to permissions. Read more in Permission Bits.
permissions.resources.groups Object A mapping of channel group names to permissions. Read more in Permission Bits.
permissions.resources.users Object A mapping of users to permissions. This resource is used only for Objects v1 operations. Read more in Permission Bits.
permissions.resources.spaces Object A mapping of spaces to permissions. This resource is used only for Objects v1 operations. Read more in Permission Bits.
permissions.resources.uuids Object A mapping of uuids to permissions. This resource is used only for App Context operations. Read more in Permission Bits.
permissions.patterns.channels Object A mapping of regular expressions to permissions for channel names that match the pattern. Read more in Patterns.
permissions.patterns.groups Object A mapping of regular expressions to permissions for channel group names that match the pattern. Read more in Patterns.
permissions.patterns.users Object A mapping of regular expressions to permissions for Objects v1 users that match the pattern. Read more in Patterns.
permissions.patterns.spaces Object A mapping of regular expressions to permissions for Objects v1 spaces that match the pattern. Read more in Patterns.
permissions.patterns.uuids Object A mapping of regular expressions to permissions for App Context uuids that match the pattern. Read more in Patterns.
permissions.meta Object The meta mapping is available for arbitrary key-value pairs, to use as your application sees fit. This mapping may be used for identity/authentication purposes, restricting the token use (in the "public key use" sense as defined by JWK), or exclusions/exceptions.
permissions.uuid String The uuid that will be exclusively authorized to use the granted token. This uuid must be supplied in the query string with every PubNub API request where the granted token is used.

Permission bits​

Name Value (Binary) Value (Hex) Value (Dec) Description
READ 0b0000_0001 0x01 1 Applies to Subscribe, Message Persistence, Presence
WRITE 0b0000_0010 0x02 2 Applies to Publish
MANAGE 0b0000_0100 0x04 4 Applies to Channel-Groups, App Context
DELETE 0b0000_1000 0x08 8 Applies to Message Persistence, App Context
CREATE 0b0001_0000 0x10 16 Applies to Objects v1
GET 0b0010_0000 0x20 32 Applies to App Context
UPDATE 0b0100_0000 0x40 64 Applies to App Context
JOIN 0b1000_0000 0x80 128 Applies to App Context

Patterns​

Patterns refer to regular expressions that you can use in the grant request to assign permissions to multiple resources at a time, instead of listing them one by one.

For an exact match, a pattern must start with the caret (^) and end with the dollar ($) sign. Otherwise, the permissions will apply to any resource with a full name containing a substring that meets the given pattern.

ttl integerpermissions object
resources object

A mapping of resource types to resource IDs.

channels object

A shallow mapping of channel names to permissions.

groups object

A shallow mapping of channel-group names to permissions.

users object

A shallow mapping of user IDs to permissions.

spaces object

A shallow mapping of space IDs to permissions.

uuids object

A shallow mapping of uuids to permissions.

patterns object

A mapping of resource types to regular expressions.

channels object

A shallow mapping of channel regular expressions to permissions.

groups object

A shallow mapping of channel-group regular expressions to permissions.

users object

A shallow mapping of user ID regular expressions to permissions.

spaces object

A shallow mapping of space ID regular expressions to permissions.

uuids object

A shallow mapping of uuid regular expressions to permissions.

meta object

The meta mapping is available for arbitrary key-value pairs to use as your application sees fit. Beware that the meta object is copied into the token verbatim; potentially being a significant source of "token bloat." This mapping may be used for identity/authentication purposes, restricting token use (in the "public key use" sense as defined by JWK), or exclusions/exceptions. PubNub reserves all keys beginning with the three-character prefix pn- for future purposes. The example shows how these may be used, but note these features are currently unimplemented. Use of undocumented reserved meta fields is considered undefined behavior. Using undefined behavior in grant requests or within tokens may break the API.

uuid string

Possible values: 1 ≤ length

The uuid that is exclusively authorized to use this token to make API requests. When this feature is enabled on the subkey, all PubNub API requests must supply the same uuid query string parameter along with the auth token issued from this Grant request.

Responses
200

Grant request was successful. The response body contains a token that can be provided to the end-user application for access to the resources contained within the token. The token can also be unwrapped by Base 64 decoding (add padding characters as necessary) and then CBOR decoding the binary. This is an example of the authentication token returned by the Grant v3 API. It can be decoded, then parsed with any CBOR parser.

{
"v":2,
"t":1568685146,
"ttl":300,
"res":{"chan":{"ch1":19}},
"pat":{},
"meta":{},
"sig":"8MzArHKY1DHZLtMOqLG+lzfkSEe8KcbngFQZB6gV1B4="
}
  • v is an integer and represents the version of the token structure. The token signature is not the same as the request signature; the two schemas are incompatible.
  • t and ttl are integers and represent timestamp and time-to-live, respectively. t is generated on the server side, but is usually within some tolerance (+/- 60 seconds) of the timestamp query parameter that generated the token.
  • resis an object that represents the mapping of resource types to resource IDs.
  • patis an object that represents the mapping of resource types to regular expressions.
  • meta is an object that represents the token metadata.
  • uuid is a string that, if requested, represents the uuid solely authorized to use the token.
  • sig is an array of bytes that represents HMAC+SHA256 signed with a PubNub confidential signing key. In the CBOR implementation, sig is a 256-bit bigint.
Schema — OPTIONAL
status integer — OPTIONAL
data object — OPTIONAL
message string — OPTIONAL
token string — OPTIONAL
service string — OPTIONAL
400

Error validating inputs, like missing required params or invalid input types.

Schema — OPTIONAL
status integer — OPTIONAL
error object — OPTIONAL
message string — OPTIONAL
source string — OPTIONAL
details object[] — OPTIONAL
message string — OPTIONAL
location string — OPTIONAL
locationType string — OPTIONAL
service string — OPTIONAL
403

Invalid signature, like a wrong secret key or character set encoding for signature computation.

Schema — OPTIONAL
status integer — OPTIONAL
error object — OPTIONAL
message string — OPTIONAL
source string — OPTIONAL
details object[] — OPTIONAL
message string — OPTIONAL
location string — OPTIONAL
locationType string — OPTIONAL
service string — OPTIONAL