How Do I Generate an API Token

You use API tokens to authenticate yourself when you make authorized API connections. You also need an API token when you associate a VMware Cloud Director instance with a VMware Cloud on AWS SDDC.

You use a combination of an API token and an access token for calls to the VMware Cloud Director service API.

An API token has a time-to-live (TTL) period, which you define when you generate the API token. After this time, if you want to continue using the APIs that rely on a token, you must regenerate the token.

After generating an API token, save the token credentials to a safe place.

You can use the API token to obtain access tokens. You can use an access token only for a single operation and within a short period. After the access token expires, you can use the API token credentials to obtain a new access token.

If you feel that the API token has been compromised, you can revoke the token to prevent any unauthorized access. When you revoke an API token, you lose the ability to perform API calls. However, access tokens obtained from the revoked API token are still valid until their expiration time (30 minutes). You generate a new API token to renew the authorization.

You can regenerate a token at any time. If you regenerate a token, you revoke all instances of the previous token. If you have used the API token, for example in one of your scripts, you must replace it with the newly generated API token.

Procedure

  1. Log in to VMware Cloud Director service.
  2. Click your user name and click My Account.
  3. On the My Account page, click the API Tokens tab.
  4. Click Generate a new API token.
  5. Enter a meaningful name of the token and in Token TTL define for how long the token is valid.
  6. Define the scopes for the token.
    Scopes provide a way to implement control over what areas in an organization your token can access - specifically which role in an organization, what services, and the level of permissions.
    Important: You can only provide your token with the roles that you have been assigned within your organization. You can check your roles in the My Roles tab.
    If you use the API token to associate a VMware Cloud Director instance with a VMware Cloud on AWS SDDC, its scope must contain the Administrator and NSX Cloud Admin service roles, as well as the Developer or the Organization Owner organization role.
  7. To get information about the users that authorize your app, select Open ID .
  8. Click Generate.
    A Token Generated pop-up window appears. You can copy, download, or print the token.
  9. Save the token credentials to a safe place, so that you can retrieve them and use them later.
    For security reasons, after you generate the token, the API Tokens page only displays the name of the token, and not the token credentials. You can no longer reuse the token by copying the credentials from this page.
  10. Click Continue.

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

  1. Generate an API token.
  2. Exchange the API token for an access token by performing a POST request to https://console.cloud.vmware.com/csp/gateway/am/api/auth/api-tokens/authorize with refresh_token={your-api-token-value} in the body of the request.
    For example:
    curl --request POST \
--url https://console.cloud.vmware.com/csp/gateway/am/api/auth/api-tokens/authorize \
--header 'content-type: application/x-www-form-urlencoded' \
--data refresh_token=<your-api-token-value>
    This request returns a response, such as:
    {
  "id_token": "eyJhbGciOiJS.......srRmGX9eYKOKMA",
  "token_type": "bearer",
  "expires_in": 1799,
  "scope": "ALL_PERMISSIONS openid group_ids group_names",
  "access_token": "eyJhbGciOiJSU.........Q6Y9Yohgw",
  "refresh_token": "B4STbh2fYFmjI9ABCv..............XeRniDiO4cBJjF82sWWprZfm7OLHn"
}

    The relevant part is access_token, which always begins with "ey", and is a JSON Web Token (JWT).

  3. Use the received access token in the Authorization header in your script's API calls.
    You can make calls to VMware Cloud Director service by using this authentication token in the Authorization header. The exact form of the header that you create by using the access token from the example is the following: 
    Authorization: 
Bearer eyJhbGciOiJSUzI1NiIsInR5NDg4SI6I................4dHnbU1RQ6Y9Yohgw
Note: Because the bearer token expires in 30 minutes, you must regenerate it by running the same request as needed.