Understanding Authentication in the REST API

PubSub+ Cloud uses Bearer authentication. Bearer Authentication requires that you include an API token in the Authorization header with each REST API call. An API token in PubSub+ Cloud is generated in the PubSub+ Cloud Console. No matter the role you have assigned, you can create an API token. The permissions you can see and can assign to the token depend on the permissions available to your user profile in the account (or organization). You can only assign the permissions that you have within an account in PubSub+ Cloud (sometimes referred to as an organization).

For example, if the user profile in the account has the Cluster & Mesh Manager Editor role, you have read and write permissions for all permissions in Mission Control. You can create an API token that allows for only the Create Services permission, but not any other permission (such as Delete My Service) to restrict the application to only the create operation for a service. Conversely, if your user profile does not have permissions available as part of their role, such as Cluster & Mesh Manager Viewer, you won't be able to create an API token with permissions that your role doesn't have.

The permissions for an API token have a higher degree of granularity than the roles you assign to a user profile. You can choose to enable or disable permissions based on the REST APIs you want to allow for your application. These permissions permit applications that have API token permissions to perform different actions. We recommend that you create an API token that has the minimum number of permissions that allow the application using the API token to function, which helps to ensure that an application performs only the actions they are scoped to perform and accesses only the required data.

Creating an API Token

You can create up to 50 API tokens (per user) in the PubSub+ Cloud Console.

Each API token permits you to set granular permission that is part of the role your user profile has been assigned. The granularity of the permissions allows you to create an API scoped to perform specific operations. You can choose to set multiple permissions for developmental and learning purposes, but Solace recommends that you set the fewest permissions necessary on the API token that you use for production environments.

The permissions you select permit you to perform specific REST API operations. To determine the permissions that a REST API operation requires, search for the API and endpoint on the Create Token page and enable the permission. For example, if you wanted to create an API token that only permits the permission to issue a GET to the https://api.solace.cloud/api/v2/platform/environments API, your search on the Create Token page determines that the View Permission is required and select the permission as shown:

After you create an API token, you can't modify the token permissions. If you require updated permissions, you must create another API token. To create an API token, perform the following steps:

1. Log in to the PubSub+ Cloud Console if you have not done so yet. The URL to access the Cloud Console differs based on your authentication scheme. For more information, see Login URLs for the PubSub+ Cloud Console.
2. On the navigation bar, User & Account , and then select Token Management.
3. Click Create Token.
4. Enter a Token Name.
5. In the Selected Permissions section, select the permissions you want to enable. You can select read and write permissions for a category and you can enable or disable individual permissions. It is best practice to select the minimum number of permissions required for your purposes and only the REST API calls you to want to permit your application to perform.

6. Click Create Token.
7. Click Copy to copy the token to your clipboard.
   Note: For security reasons, this dialog doesn't appear again. If you lose the token you must regenerate the API token or create another token.
8. Click Close.
9. To use the token, put the value that you copied in the following REST header for any calls to your account:

Authorization: Bearer <Your New API Token>

You can use this reference to try the APIs. For more information, see Using the API Token in this Reference.

Using the API Token in This Reference

After you have your API token created, you use it to generate a code snippet, generate a cURL command, and even try it using the PubSub+ Cloud REST API Reference. Ensure that you have an API token with the permissions for the call you want to create before you follow these steps:

1. On the PubSub+ Cloud REST API reference page, select an API call that you want to use.

📘

The calls that you can use with your account depend on the products and roles assigned to your user profile.

2. On the right pane beneath Authentication, paste your API token in the Bearer field. You can choose the code to generate and the default is a Shell. You you can select any language to generate an example under Language. You can select from more languages if you click the kebab icon on the right.
   
3. (Optional) You can click the Base URL drop-down menu to select the Base URL to use. For more information, see Specifying the Correct Base URL for REST API Endpoints.
   
4. To try the command, perform one of the following actions:

• click Try It
• for Shell commands, copy the cURL command and run it in a CLI
• copy the specific code and run it in your application.

After you run the command, check the HTTP response code to determine if it was successful. If not, troubleshoot using the HTTP response code and error code.

Regenerating an API Token

Lost API tokens can't be retrieved, but they can be regenerated. A regenerated API token has the same permissions. If you regenerate an API token, you must update all applications and scripts that use the old token to continue accessing the REST API for PubSub+ Cloud. To regenerate an API token, perform the following steps:

1. If you have not done so, log in to the PubSub+ Cloud Console. The URL to access the Cloud Console differs based on your authentication scheme. For more information, see Login URLs for the PubSub+ Cloud Console.
2. On the navigation bar, click User & Account, and then select Token Management.
3. Click More Actions for the token that you want to delete and select Regenerate Token.
4. Click Regenerate.
5. Click the Copy button to copy the token to your clipboard.
6. Click Close.

The API token should be on your clipboard. You can paste it into your application code for usage with the REST API.

Deleting an API Token

It's a good security practice to remove outdated API tokens and ones that you no longer use. API tokens do not expire. After you delete an API token, it can't be restored and applications can no longer use that API token to make API calls. To delete a token, perform the following steps:

1. If you have not done so, log in to the PubSub+ Cloud Console. The URL to access the Cloud Console differs based on your authentication scheme. For more information, see Login URLs for the PubSub+ Cloud Console.
2. On the navigation bar, click User & Account,, and then select Token Management.
3. Click More Actions for the token that you want to delete and select Delete Token.