Managing API Tokens

Information about using API tokens is also available at v2 REST API documentation.

To use the REST APIs available in PubSub+ Cloud, you need an API token to authenticate and authorize REST requests. You assign permissions to tokens to permit applications that have the token to perform various actions and access various features. You include the API token in the Authorization Bearer header when you make a REST call.

It is a best practice to create different tokens for different applications and provide only the minimum number of permissions that the application requires so you can to ensure that an application can make only the necessary changes, access only the necessary features, or access only the required data to function correctly. You can create up to 50 API tokens per user in an account.

This section includes the following tasks:

Considerations for Using API Tokens

Before you start managing API tokens for using the PubSub+ Cloud REST APIs, you should be aware of the following considerations:

  • You cannot create API tokens with permissions beyond your assigned role. The permissions you can see and set for the token depend on your assigned role. If you don't see some permissions that you need, you may not have the required permissions for your account.
  • If your role changes, whether directly or due to changes in how users are authenticated and authorized, and you lose one or more of the permissions you had when you created the tokens, tokens with permissions that you no longer have are invalidated.
  • The REST API URL to use depends on the regional site where you have your account. All REST API examples use the URL for the United States. The REST API to use for each regional site is as follows:
    • Regional Site REST API BASE  URL
    United States https://api.solace.cloud/
    Australia https://api.solacecloud.com.au/
    European Union https://api.solacecloud.eu/
    Singapore https://api.solacecloud.sg/

Creating an API Token

When you create tokens for production use you should set the fewest permissions necessary for the application to work as expected. After you create an API token, you can't modify the token permissions. If you require updated permissions, you must create another token.

To create an API token, perform these 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 Logging In to the PubSub+ Cloud Console.
  2. On the navigation bar, select 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 that you want to enable. You can select read or write permissions for an entire category and you can enable or disable individual permissions.

    On the API Token Management page, the URLs do not appear beside the permission that align with the PubSub+ Cloud v2 REST APIs, which offer an improved experience. For more information, see PubSub+ v2 REST API Reference.

  6. Click Create Token.

  7. Click Copy to copy the token to your clipboard.

    For security reasons, this dialog does not appear again after you close it. If you lose the token you must regenerate it or create a new one.

  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 Token>

    Alternatively, you can use development tools (such as Postman or curl) to learn about how to use the PubSub+ Cloud REST API . Our subsequent tutorials use Postman. For more information, see Using an API Token with Postman.

Creating an API Token for Connector Wizards

You can use an API token for authorization with Connector Wizards and the Click to Connect Wizards for Bridges in PubSub+ Broker Manager for appliances, software event brokers, and event broker services. The Connector Wizards help you create REST Delivery Points (RDPs), and the Click to Connect Wizards help you create Message VPN bridges, Kafka bridges, and configure clusters for Dynamic Message Routing (DMR).

The API token that you create to use with the wizards must have at least one of the following permissions:

  • Get Services with Management Credentials allows you to see all services within your organization.
  • Get My Services with Management Credentials allows you to see only services that you've created within your organization.

The wizards use the API token once to retrieve the service details, and do not store the API token. You can remove or regenerate an API token after the wizard uses it.

To create an API token to use for connection wizards in Broker Manager, perform these 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 Logging In to the PubSub+ Cloud Console.
  2. On the navigation bar, click User & Account , and then select Token Management.
  3. Click Create Token.
  4. Enter a Token Name.
  5. In the Mission Control section, select one of the following permissions:
    • Under My Service, select Get My Services with Management Credentials.
    • Under Organization Services, select Get Services with Management Credentials.
  6. Click Create Token.

  7. Click Copy to copy the token to your clipboard.

    If you lose the copied token before you use it, you must regenerate the token or create a new one.

You now can now use the token in PubSub+ Broker Manager to create a VPN bridge or clustering link. For more information, see Creating a Message VPN Bridge with Click-to-Connect.

Regenerating an API Token

You cannot retrieve lost API tokens, but you can regenerate them. Regenerating a token creates a new token with the same permissions. If you regenerate an API token, you must update all applications and scripts that use the token to allow them to continue accessing the REST API for PubSub+ Cloud.

If your permissions have changed since you created the token and you no longer have a permission that is included in the token, you cannot regenerate it.

To regenerate an API token, perform these 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 Logging In to the PubSub+ Cloud Console.
  2. On the navigation bar, click User & Account , and then select Token Management.
  3. Click More Actionsfor the token that you want to replace and select Regenerate Token.
  4. Click Regenerate.
  5. Click Copy to copy the token to your clipboard.
  6. Click Close.

You can paste the API token from your clipboard into your application code for usage with the REST API or use it with the Click-to-Connect wizard.

Deleting an API Token

It's a security best practice to remove outdated API tokens and ones that you no longer use. You cannot restore an API token after you delete it, and applications can no longer use that API token to make API calls.

To delete a 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 Logging In to the PubSub+ Cloud Console.

  2. On the navigation bar, click User & Account , and then select Token Management.
  3. Click More Actionsfor the token that you want to delete and select Delete Token.

Using an API Token with Postman

Generally, you use an API token in the code for your applications; however, you can make REST API messages from your development environment using development tools such as curl or Postman. Our tutorials show how to use the REST APIs using Postman (versions 6.1.3 or greater) as a visual REST API development tool. Before you can complete the steps in this section, you must first create an API token.

To use the API token, you must include it in Authorization header, which is by default set to use Bearer authentication. To set up Postman to make REST API calls, we recommend that you set up an environment variable to configure the API token using these steps:

  1. To authorize REST requests from Postman to PubSub+ Cloud, you must set the Postman apiToken to the API that you've created. For more information, see Creating an API Token.
    1. Set the Postman Environment to PubSub+ Cloud.

      Screenshot showing the options described in the surrounding steps.

    2. Click the Environment Quick Look button located next to the Environment drop-down list.
    3. In the dialog box, click Edit next to Solace PubSub+ Environment.
    4. Paste the API token in the value field of the apiToken key into the field. If the apiToken field doesn't exist, create it.

      Screenshot showing the options described in the surrounding steps.

    5. If you are modifying a service, it's also useful to add a serviceId variable so you don't need to specify it in the URL for each REST API call. You must do this step after you've created a event broker service. Alternatively, you can fill the variable in the REST API calls. An easy way to find your serviceId is to open the service details on the PubSub+ Cloud Console and find the identifier at end of the URL for your service.
    6. Click Update.

Now you have an API token and have set up Postman to use it. You can now use Postman to learn how to use the PubSub+ Cloud REST API.

Next Steps

After you have created an API token and configured Postman (or your application) to use the token, you can learn how to perform some tasks with the PubSub+ Cloud REST API such as: