Authentication
Before a client or server can send requests to PUBQ—like subscribing to channels or publishing messages—it needs to authenticate with PUBQ by using a PUBQ API key. This API key is essential for the authentication process.
PUBQ API keys
Each PUBQ application can be linked with one or multiple API keys to enable direct authentication with PUBQ or to issue tokens. API keys can be generated with varying capabilities, and any tokens issued using a particular API key will only allow a subset of those capabilities. This provides flexibility in managing access and capabilities within the PUBQ platform.
API key elements
A PUBQ API key string has the following pattern:
A PUBQ API key consists of the following 3 components:
1. Application ID
The public application ID. example: q4D9G2
2. Application key ID
The public application key ID. example: rGQK1W
The application ID and application key ID together (the part before the colon) like q4D9G2.rGQK1W is the public API key ID.
3. Application key secret
The application key secret (the part after the colon) and should never be shared with untrusted parties. example: 9pWbndVJg50MaOPAapAx7LQ_zKw6YvXl2B
The API key secret is private and should never be made public. This API key string is utilized in all PUBQ SDKs and for authentication with the REST API.
Create an API key
API keys are created in the PUBQ dashboard.
- In your PUBQ dashboard, create an application or select an existing one.
- Navigate to Keys tab.
- Click the Create a new API key button.
- Enter a name for your API key – this will assist you in identifying the specific key when you have created many keys.
- Select the permissions you want to apply to the key. Clients connecting with this key will be restricted to these capabilities.
- Optionally select whether you want to restrict the scope of the key to specific channels using resource names and wildcards.
Available authentication mechanisms
The two available authentication mechanisms to authenticate with PUBQ are:
- Basic authentication uses your PUBQ API key directly.
- Token authentication utilizes short-lived tokens for access. These tokens are periodically renewed and can be revoked if necessary.
Client-side authentication
Token authentication is the recommended authentication mechanism on the client-side, as it offers finer-grained access control and reduces the risk of exposing your PUBQ API key.
In production systems, you should never use basic authentication on the client-side, as it exposes your PUBQ API key. API keys lack an expiry, so once compromised, they could be exploited indefinitely by an attacker.
Tokens have an expiry, which means there is only a limited period during which a compromised token can be utilized. Additionally, it is possible to revoke tokens if necessary for security reasons.
Server-side authentication
Use basic authentication on the server-side. Token authentication should never be used on the server-side, as it introduces unnecessary overhead, requiring the server to periodically make token requests for self-authentication.
Selecting an authentication mechanism
When deciding on the authentication method you will use, it is recommended to consider the principle of least privilege.
A client should ideally possess only the necessary credentials and rights required to achieve its objectives. This approach minimizes the potential for abuse by an attacker in case the credentials are compromised.
The following table offers guidelines on factors to consider when selecting your authentication method.
Many applications will naturally adopt a mixed strategy:
In many cases, a mixed strategy is advisable, where one or more trusted application servers use basic authentication to access the service and issue tokens over HTTPS, while remote browsers and devices use individually issued tokens.
| Scenario | Basic auth | Token auth | Description |
|---|---|---|---|
| Your scripts may become exposed. | No | Yes | If the script, program, or system containing the key is exposed, such as on a user's device, embedding an API key should be avoided, and token authentication should be used instead. However, if the script resides in a secure environment, such as your own server, using an API key with basic authentication is acceptable. |
| Your connection might be insecure. | No | Yes | If there is a potential for the client's credentials to be exposed, either directly or over an insecure or insecurely proxied connection, it is advisable to utilize token authentication. However, if you are confident that the connection is secure and unmediated, basic authentication is an acceptable option. |
| You have no server to control access. | Yes | No | If you don't have your own server for performing authentication and distributing tokens to users, you will need to rely on basic authentication. |
| You necessitate fine-grained access control. | No | Yes | If you need to grant privileges on a per-user basis, it's advisable to opt for token authentication. However, if you only require a few access control groups, basic authentication is a reasonable choice. |
| Users require limited periods of access. | No | Yes | If you require users to have access for a specific timeframe or the capability to revoke access, token authentication is necessary. If users can maintain continuous access, basic authentication is suitable. |
| Users must identify themselves. | Partial | Yes | If the user can be relied upon to identify themselves, basic authentication is acceptable. However, if the user cannot be trusted, token authentication is preferable as it enables a trusted token distributor to perform user identification instead. |
