Introduction

This is not the latest version of this API. Consider migrating to Access Manager.

PAM v2 provides fine-grained access controls to PubNub Data Streams. It presents a minimal REST API for secure administration tasks, and transparently protects Data Stream resource access. This document divides these two responsibilities clearly into their own sections: REST API and ACL Enforcement.

Global Permissions​

Do not provide auth nor channel in the signed-content query-string parameters

Channel Permissions​

Provide only a channel parameter, but not auth parameter, this then sets permissions on the channel itself overriding any auth-key permissions

AuthKey Permissions​

Provide both auth and channel parameters to set the permissions for one or more channels and one or more auth-keys

Both auth and channel accept comma-separated lists.

Permission Mapping​

  • Permissions on channel resource: read, write, delete, get, update, manage, join
  • Permissions on channel-group resource: read, manage
  • Permissions on uuid resource: get, update, delete Note that wildcards are NOT supported on the uuid resource. Also, you cannot grant permissions for the uuid resource and other resources in the same operation.

Signature Generation​

The signature is used to verify if the request was signed with the secret key associated with the PubNub subscribe key.

  • Signature is computed using HMAC+SHA256 with the user's secret key as the signing key.
  • The signing message is composed of the HTTP method, publish key, request path, query string, and request body (or empty string) in the following format {method}\n{pub_key}\n{path}\n{query_string}\n{body}
  • Query parameters must be sorted lexicographically (case-sensitive) by a key. Duplicate keys are not allowed.
  • Replace special characters in the query parameters using the %xx escape. Letters, digits, and the characters _.- are never quoted. For example, ~user/1_2.3-4 should be encoded %7Euser%2F1_2.3-4. Uppercase characters in the percent escapes are required. In other words, all characters matching the RegEx /[^0-9a-zA-Z\-_\.]/ must remain unencoded.
  • Space characters must be replaced by %20 (NOT the + character).
  • Each key-value pair must be separated by an ampersand (&) character.
  • Unicode characters must be broken up into UTF-8 encoded bytes before percent-encoding.
# Example query string containing unicode characters
timestamp=1234567898&PoundsSterling=£13.37

# The same query string after sorting and percent-encoding
timestamp=1234567898&PoundsSterling=%C2%A313.37
  • The request body must be appended to the message verbatim (byte-for-byte, as provided in the request).