You use API tokens to authenticate yourself when you make authorized API connections. An API token is exchanged for an access token and authorizes access per organization. You generate API tokens from your account page in Cloud Services Console or through the VMware Cloud services.

Tokens are generated using a special algorithm that picks up alphanumeric characters. Each token is a unique 65 characters combination. When you generate a token, you determine its duration and scopes:
  • A token's Time to Live (TTL) can range from several minutes to several months, or set to never expire. The default duration is six months.
  • Scopes provide a way to implement control over what areas in an organization your token can access - specifically which role in an organization, and what services and the level of permissions.

Prerequisites

Ensure a secure and protected storage location for your API tokens.

Procedure

  1. Click your user name in the upper-right corner of the toolbar, and then click My Account.
  2. Select the API Tokens tab.
  3. Click Generate a New API Token.
  4. Enter a name for the token.
  5. For Token TTL, specify the desired lifespan of the token.
    Important: A non-expiring token can be a security risk if compromised. If this happens, you must revoke the token.
  6. Define scopes for the token.
    If required, you can select All Roles and give your token access to all the organization and service roles.
    Note: Even if you assign All Roles access to your token, it will have only those access roles which your user account supports. To view the organization and service roles you have, from the My Account page select the My Roles tab.
  7. Select the Open ID check box to retrieve an Open ID compliant token with extended user details.
  8. For Email preferences, select if you want an expiration reminder and specify when to send the reminder.
  9. Click Generate.
    A dialog displays indicating that the token was generated.
  10. Save the token credentials to a safe place so you can retrieve them to use later on.
    Important: Make sure to store this token in a safe place where you can access it. Once you click "Continue", you will not be able to retrieve this token again.
    For security reasons, after you generate the token, we only display the name of the token on the API Tokens page and not the token credentials. This means that you will no longer be able to reuse the token by copying the credentials from this page.
  11. Click Continue.
    In addition to API tokens, you can use OAuth apps to authenticate your applications. To see when to use OAuth apps instead of API tokens, see What Is the Difference Between OAuth Apps and API Tokens.

    To return to the Carbon Black Cloud console, click Services and then launch the Carbon Black Cloud service.

What to do next

After generating the API tokens, you must now use it to call the APIs:
  1. Use your API Token to get an Access token which typically has a 30 minute time to live (TTL). See: How Do I Generate API Tokens
  2. Use the returned token in the following call:
    curl --location -g --request POST '<CSP URL>/csp/gateway/am/api/auth/api-tokens/authorize' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'api_token=<API Token here>'