You use API tokens to authenticate yourself when you make authorized API connections. Previously called an OAuth Refresh token, 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. On the Cloud Services Console toolbar, click your user name and select My Account > API Tokens.
  2. Click the Generate a New API Token link.
  3. Enter a name for the token.
  4. Specify the desired lifespan of the token.
    Note: A non-expiring token can be a security risk if compromised. If this happens, you must revoke the token.
  5. Define scopes for the token. Your selection must be based on the roles supported by your user account.
    Scope Description
    Organization Roles Organization roles determine a user's access to the Organization's resources.
    • Select one or more Organization roles for your API Token.
    Service Roles Service roles are built in pre-defined sets of permissions that grant access to VMware Cloud services.
    • Use the arrow icon next to a service name to expand the roles available for that service, then select one or more service roles for your API Token.
    Permissions Some services allow you make a more granular selection by assigning a limited set of the permissions available for a service role.
    • When you select a service role, the available permissions are displayed in the right side of the table. Select the relevant service permissions for your API 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.
  6. (Optional) Select the Open ID check box to retrieve an Open ID compliant token with extended user details.
  7. (Optional) Set an email preference to receive a reminder when your token is about to expire.
  8. Click Generate.
  9. Save the token credentials to a safe place so you can retrieve them to use later on.
    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.
  10. 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.

Example: Using an API Token to Interact with VMware Cloud Service APIs

You can use an API token to interact with our APIs by exchanging it for an authentication token.
  1. Generate an API token.
  2. Perform POST to https://console.cloud.vmware.com/csp/gateway/am/api/auth/api-tokens/authorize.
  3. In the header, include the following requests:
    • accept: application/json
    • content type: application/x-www-form-urlencoded/
  4. In the body, include the refresh_token={token value} request.
  5. Use the authentication token in the csp-auth-token header in your script's HTTP calls.