Understanding Authentication When Using 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. You can generate an API token in the PubSub+ Console Cloud. All users can create API tokens. The permissions you can see and can assign to an API token are limited to the permissions available to your user profile in the account (or organization).

For example, if your user profile in the account has the Cluster & Mesh Manager Editor role, you have read and write access to create, delete, and update event broker services in Mission Control. When you create an API token you can assign a subset of permissions. For example, you can create an API token that allows access to only create services ( Create Services permission), but not update or delete services to restrict the functionality an application is permitted. Conversely, if your user profile does not have the permissions available as part of their role, such as Cluster & Mesh Manager Viewer role, 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 that are used by your application. The permissions enabled in a token allow applications 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. When you limit the permissions, it ensures that an application can perform only the actions they are allowed and access only the required data they are permitted.

When you use API tokens, is important to remember:

• you can only create up to 50 API tokens (per user) in the PubSub+ Cloud Console
• the secret for an API token cannot be viewed - if you lose it, you must regenerate the API token
• if you lose the permissions in your user account that were previously assigned to an API token when you had the permissions, the API token is deleted
• you are authenticated to call endpoints in the account (organization) where the API token was created and all calls run in the context of that account

Creating API Tokens

You can set a granular set of permissions for each API token. You are limited to setting only the permissions that are assigned to your user profile. The granularity of the permissions allows you to create an API token scoped to perform specific operations. You can choose to set multiple permissions based on your use case or requirements, but Solace recommends that you enable the minimum number of permissions in the API token and abide by the principle of least privileges. After you create an API token, you can't modify the token permissions.

The permissions that you enable for an API token allow you access to perform specific REST API operations in PubSub+ Cloud. To determine the permissions that a REST endpoint requires, you can either:

• Find the required permissions based on the API reference
• Find the required permissions based on the endpoint URLs

After you determine the permissions that you require, you can create your API token.

Finding the Required Permissions Based on the API Reference

You can determine the required permissions by referring to the API documentation for the endpoints you want to use (if it's available) and then enabling the permission when you create your API token.

For example, for the Get a list of applications endpoint, the permission listed is event_designer:access in the API reference in the heading Token Permissions as shown below:

Continuing with our example, if you wanted to create an API token that allows you to perform the GET operation to the https://api.solace.cloud/api/v2/architecture/applications endpoint, you would search on the Create Token page for the event_designer:access and find that the permission corresponds to the Access to Event Portal Designer permission. After you select the Access to Event Portal Designer permission and click Create Token , you have an API token that allows an application to perform the GET operation to the https://api.solace.cloud/api/v2/architecture/applications endpoint.

Finding the Required Permissions Based on the Endpoint URLs

You can search for the endpoint URL on the API Token Management page to determine the required permission when you create your API token. Note that this is a legacy way of determining the permissions as most of the endpoints have the required API token permissions documented in the API reference.

For example, if you wanted to create an API token that only permits an application to issue a GET operation to the https://api.solace.cloud/api/v2/platform/environments endpoint, you would search on the Create Token page for the URL and find that corresponds to the View Environment permission. If you select the View Environments permission and click Create Token , you have an API token that allows an application to perform the GET operation to thehttps://api.solace.cloud/api/v2/platform/environments endpoint:

Steps for Creating an 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. Ensure you have the correct account selected if you belong to multiple accounts.
3. On the navigation bar, click User & Account , and then select Token Management.
4. Click Create Token.
5. Enter a Token Name.
6. In the Selected Permissions section, select the permissions that you want to enable. You can select read and write permissions for a category, and enable or disable individual permissions. We recommend that you enable only the minimum number of permissions required to use the REST endpoints for your application. For more information about determining the permissions to choose, see Finding permission based on the listed API token permission and Finding the permission based on the endpoint
7. Click Create Token.
8. 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.
9. Click Close.
10. 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.

Using the API Token in This Reference

After you create your API token, you can use it to generate a code snippet, generate a curl command, and even use Try It to issue the command directly from 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.

📘

Note

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 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) 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 it was not, troubleshoot using the HTTP response code and error code.

Regenerating an API Token

Lost API tokens cannot 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. On the navigation bar, click User & Account, and then select Token Management.
2. Click More Actions for the token that you want to delete and select Delete Token.