Managing API Tokens

To use the PubSub+ Cloud's REST API, you need an API token. The API token must be included in the Authorization Bearer header when you make a REST call. To get an API token, you must generate it in the PubSub+ Cloud Console. You generate and manage API tokens at an account level and also configure the permissions it has (i.e., a subset of the permissions you have when you log in to the PubSub+ Cloud). You need an API token to authenticate and authorize REST requests. To learn more about using API tokens, see Understanding API Token Permissions.

To manage API tokens, you can do the following:

To learn more about the REST API and how to use can use with tools such as Postman, see Using an API Token with Postman.

Prerequisites

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

  • A PubSub+ Cloud account.
  • A role assigned that allows you create an API token and assign the proper permissions to that API token. In the steps below, we show the permissions available for assigning if your account had the Administrator role.

Creating an API Token

The following steps show you how to create an API token that has the permissions to use a majority of the PubSub+ Cloud REST API, Event Portal REST API, and event broker service REST API. Multiple permissions are recommended for developmental and learning purposes, but not for production use. It's important to note that after you create the API token, you cannot modify a token's permissions. If you require updated permissions, you must create another token. You can use the following steps to create an API token:

  1. Log in to PubSub+ Cloud. If you belong to multiple accounts (or Workspaces), select the account you want to create an API token for when prompted after logging in.
  2. At the bottom of the left-hand menu, click the user icon, and then click Token Management.

  3. In the top-right corner, click the Create Token button.

  4. On the Create Token page, in the Token Name box, type a unique name for the API token.
  5. On the Select Permissions section, click the toggle Greyed out slider indicating off beside the permission you want to enable . To determine which permissions to enable, see the REST endpoints beside each permission on the Create Token page and enable the permissions for the endpoints you want to use.

    The permissions you can set and see depend on your assigned account role. If you don't see some permissions (or see additional permissions) listed on the Create Token page as shown in the illustration, you may not have the required permissions for your account. Contact your account administrator or Solace support if there is a problem with your permissions.

    The permissions shown below are useful for completing the tutorials and for development purposes only to fully utilize the REST API capabilities. API tokens that you use in production must assign only the minimum set of permissions (a subset of the above permissions) that are required for your client applications to function. For example, don't assign a permission such as Create User or Delete User if the application never needs to manage users. For more information, see Understanding API Token Permissions.

     

    The example shown below is useful for completing the tutorials or for development purposes only. The recommended practice is to create multiple API tokens with a subset of required permissions.

    My Service and Organization Service permissions:

    Cloud Services, Account Management, and Event Portal permissions (continued from previous page):

    />

  6. Click the Generate Token button at the bottom of the page.
  7. In the dialog box that appears, click the Copy button to copy the API token to your clipboard for later use (e.g., use with the REST API or for your Click-to-Connect wizard in the PubSub+ Broker Manager).

    Note: For security reasons, this dialog doesn't appear again. If you lose the token or forget to copy it to your clipboard, you must regenerate the API token or create one.

You can now use this API token to manage your event broker services using the PubSub+ Cloud REST API or for the Click-to-Connect wizards in the PubSub+ Broker Manager.

To use this API token, put the value that you copied in the following REST header for any calls to your account (Workspace):

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 to configure Postman with the API token, see Using an API Token with Postman.

Creating an API Token for Click-to-Connect

For appliances and software event brokers 9.7 (or later), you can use an API token for authorization with Click-to-Connect wizards. You can use Click-to-Connectwizards to create VPN bridges and configure clusters in PubSub+ 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, which allows you to see all services within your account (Workspace)
  • Get My Services, allows you to see only services that you've created within your account (Workspace)

The API tokens that you use for Click-to-Connect can be removed or regenerated because the API token is used only once to retrieve the service details and is not stored.

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

  1. Log in to PubSub+ Cloud. If you belong to multiple accounts (or Workspaces), select the account that you want to create a VPN bridge or configure the cluster for.

    If you're already logged in to the PubSub+ Cloud and belong to multiple accounts (Workspaces), ensure that you select the account that you want to create an API token for. To do this, at the bottom of the navigation bar, click User & Account User icon in the PubSub+ Cloud Console, and select the account you want to create an API token for.

  2. On the navigation bar, click User & Account User icon in the PubSub+ Cloud Console, and then select Token Management.

  3. In the top-right corner, click the Create Token button.

  4. On the Create Token page, in the Token Name field, type a unique name for the API token.
  5. On the Select Permissions section, enable one of the following permissions using the toggle Greyed out slider indicating off beside that permission:
    • Get Services, which allows you to see all services

    • or Get My Services, allows you to see only services that you've created:

    For a description of the permissions or other permissions you want to enable, see the REST endpoints beside each permission on the Create Token page.

  6. Click the Generate Token button at the bottom of the page.
  7. In the dialog box that appears, click the Copy button to copy the API token to your clipboard.

    Note: For security reasons, this dialog doesn't appear again. If you lose the token or forget to copy it to your clipboard, you must regenerate the API token or create one.

  8. For your PubSub+ event brokers, in PubSub+ Broker Manager, select the Token tab, and then paste the API token you copied from the previous step into the Token field. Here's an example of creating a new VPN bridge:

You should now be authorized to create a VPN bridge or clustering link.

Regenerating an API Token

If you have lost the API token that was generated when you created your API token or you simply want to change the API token, you can regenerate it. The API token, if lost cannot be retrieved. In this situation, you must regenerate the API token, but you must ensure that you modify any calls made to the REST API from your client applications or test applications. You can regenerate your API token using the following steps: 

  1. Log in to PubSub+ Cloud. If you belong to multiple accounts (or Workspaces), select the account you want to regenerate an API token for when prompted after login.
  2. At the bottom of the navigation bar, click User & Account User icon in the PubSub+ Cloud Console, then select Token Management.

  3. On the Token Management page, click the the name of the token that you want to regenerate.
  4. On the View Token page, click Regenerate Token, and click Yes when prompted.
  5. In the dialog that appears, click the Copy button to copy the token to your clipboard.

The API token should now 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 dated API tokens and ones that you don't use. To delete a token, follow the following steps:

  1. Log in to PubSub+ Cloud. If you belong to multiple accounts (or Workspaces), select the Workspace you want to delete an API token for when prompted after login.
  2. At the bottom of the left-hand menu, click your user, and then click Token Management.

  3. Click Delete beside the name of your token you want to remove and click Yes in the confirmation dialog. It's important to note that once an API token has been removed, it cannot be restored and applications can no use that API token to make API calls.

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 it's accessible, 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 Solace PubSub+ Cloud.

    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.

    5. If you are modifying a service, it's also useful to add a serviceId variable as well so you don't need to specify it in the URL for each REST API call. This must be done 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 look at the identifier located at end of the URL for your service as shown below:

    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.

Understanding API Token Permissions

Individual permissions are assigned to API Token rather than roles. These permissions permit the user (application) of the API token to perform different actions and access different features. Typically, you assign the minimum number of permissions allowed to application using an API token to function. This helps to ensure that only authorized applications can make only the necessary changes, access only the necessary features, or access only the required data to function correctly. For example, permissions such as Create Users or Delete Users are permissions that you don't want to provide all users.

In addition, it's a good idea to use multiple tokens with subsets of require permissions. Having a token that has multiple permissions is not recommended.

Instead, those type of permissions should be restricted to users or client applications are used for administrative purposes. For information about the permissions, see the descriptions on the Create Token page of the Cloud Console.

Next Steps

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