Capabilities

API keys and PUBQ-compatible tokens, have a set of capabilities assigned to them that specify which operations (such as subscribe or publish) can be performed on which channels.

API keys are long-lived, secret and typically not shared with clients. API key capabilities are configured using the dashboard.

PUBQ-compatible tokens are designed to be shared with untrusted clients, are short-lived, and can be configured and issued programmatically. See selecting an authentication mechanism to understand why token authentication is the preferred option in most scenarios.

Permission operations

The following permission operations are available for API keys and issued tokens:

Channel restrictions

You can choose to restrict the API key to match a set of channel names. If you’ve chosen to restrict the API key to selected channels, you can use a comma separated list of resources the API key can access, making use of wildcards to provide access to areas of your app. It is worth noting an API key will provide the same capabilities to all resources it has access to.

Resource names and wildcards

Each resource can match a single channel, for example, my-channel, or multiple channels using wildcards (*).

Wildcards can only replace whole segments (segments are delimited by :) of the resource name. A wildcard at the end of the name can arbitrarily replace many segments. For example:

• A resource of * will match any channel.
• A resource of namespace:* will match any channel in the namespace namespace, including namespace:channel, and namespace:channel:other.
• A resource of foo:*:baz will match foo:bar:baz, but not foo:bar:bam:baz.
• A resource of foo:* will match expressions such as foo:bar, foo:bar:bam, foo:bar:bam:baz, as the wildcard is at the end.
• A resource of foo* (without a colon) will only match the single channel literally called foo*.

Token capabilities

PUBQ Tokens are issued from an existing API key and their capabilities can, at most, match the permissions and restrictions of the issuing API key.

If an API key must be shared with a third party, then it is recommended that the principle of least privilege is considered, assigning only the capabilities needed by that third party. Thus, any PUBQ requests authenticated using that API key or PUBQ-compatible tokens associated with that API key, will be restricted to the permissions and restrictions assigned to the API key.

View the API key capabilities

To view the capabilities for an existing API key:

• Sign into your PUBQ dashboard.
• Select an application.
• Select the Keys tab.
• Click the button for the key you want and then click the Settings button to check the capabilities for the key.