Managing API Tokens

The information on 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, much like you would assign permissions to user roles. These permissions permit applications that have the token to perform different actions and access different features. It is a best practice to create different tokens for different applications to provide only the minimum number of permissions that allow the application using the API token to function. This helps 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.

You must include the API token in the Authorization Bearer header when you make a REST call.

This section includes the following tasks:

Before You Begin

Before you can start managing API tokens for using the PubSub+ Cloud REST APIs, you require the following:

  • A role assigned that allows you to create an API token and assign the proper permissions to that API token. The permissions you can see and set depend on your assigned account role. If you don't see some permissions that you need, you may not have the required permissions for your account.
  • 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. Here's a summary of the different URLs for each regional site that you will use for the REST API.
    • Regional Site REST API BASE  URL
    United States https://api.solace.cloud/
    Australia https://api.solacecloud.com.au/
    Singapore https://api.solacecloud.sg/

Creating an API Token

The following steps show you how to create an API token. You can set multiple permissions for developmental and learning purposes, but you should set the fewest permissions necessary for production use. 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 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 into 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 that 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.

    On the API Token Management page, for some permissions, the URLs no longer appear beside the permissions. Solace has changed these permissions to align with the PubSub+ Cloud v2 REST APIs, which offer a much improved experience. For more information, see PubSub+ v2 REST API Reference.

    Screenshot showing the settings described in the surrounding steps.

  6. Click the Create Token button.

  7. Click the Copy button 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 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 Click-to-Connect

For appliances, software event brokers, and event broker services, you can use an API token for authorization with the Click-to-Connect wizards. You can use Click-to-Connect wizards to create Message VPN bridges and configure clusters in Broker Manager.

The API token that you create must have at least one of the following permissions, or the Click-to-Connect wizards won't work:

  • 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.

You can remove or regenerate the API tokens that you us for the Click-to-Connect wizard after the wizard uses them. The wizard uses the API token once to retrieve the service details, and does not store the API token.

You can use the following steps to create an API token for use with Click-to-Connect:

  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 into 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 Selected Permissions section, select one of the following permissions:
    • Get My Services with Management Credentials:

      Screenshot showing the settings described in the surrounding steps.

    • or Get My Services with Management Credentials:

      Screenshot showing the settings described in the surrounding steps.

  6. Click the Create Token button.

  7. Click the Copy button 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.

To regenerate 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 Logging into 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 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 or use it with the Click-to-Connect wizard.

Deleting an API Token

It's a good security measure 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 into 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: