VMware Cloud APIs

Getting Started with VMware Cloud on AWS REST APIs in 5 Minutes

For a high level overview of VMware Cloud on AWS APIs skip to the section About VMware Cloud on AWS API Programming below. To get you started quickly let’s dive into the necessary steps to enable you to begin calling APIs.

Step 1 - Obtain a VMware Cloud on AWS API Token

Calling APIs requires an API Token and you’ll need to navigate to the VMware Cloud on AWS portal and create a new API Token (requires login). Your API Token will be an alpha-numeric string.

Step 2 - Exchanging your API Token for an Access Token

With your API Token you’ll need to use the CSP Identity and Access Management group of APIs and fetch an “access token” which will be passed as part of each subsequent VMware Cloud on AWS API request. See below for more details on refresh tokens and handling expiration. Here’s the API you’ll need:

POST Exchange Scoped Token For Access (requires login)

Step 3 - Fetch your Organization ID

Your VMware Cloud on AWS account will be associated with one or more organizations and most APIs require an Organization ID. You can obtain your Organization ID from the VMware Cloud on AWS UI or using In this step we’ll look at fetching a list of your organizations including the orgID using this API:

GET List Organizations

Step 4 - Create your first SDDC

Now that you’ve authenticated and fetched your OrgId you’re ready to create your first SDDC. For that you’ll want to use this API:

POST Create SDDC

Step 5 - Polling the creation status of your SDDC

Creating a new SDDC can take awhile and the above API returns a Task structure which includes an “id” field that identifies the task. The structure also includes a “status” field which you can use to determine the state of task. Using the task “id” field you can poll to fetch up-to-date information on the status of the task using this API:

GET Get Task

Step 6 - Fetching details about your SDDC

Once your SDDC is created, using your Organization ID and your SDDC ID, you can fetch detailed information about it using this API:

GET Get SDDC

About VMware Cloud on AWS API Programming

The VMware Cloud on AWS APIs are organized around REST (“Representational State Transfer”) operations for performing create, retrieve, update and delete operations on VMware Cloud on AWS resources. For ease of use and security, REST builds on the standard web protocols HTTP and HTTPS, using the normal network ports 80 and 443, which are both open in most data centers, and uses standard HTTP response codes and verbs.

As a Cloud Service VMware Cloud on AWS APIs are not publicly available and require an API Token for programmatic use. You will need a VMware Cloud Services account to generate an API Token which you will use to programmatically call APIs from your programming language of choice.

Authentication and Authorization

When working with VMware Cloud on AWS APIs it’s important to understand the difference between authentication and authorization. As a user you authenticate to VMware Cloud Services with the username and password provided to you. However, as a developer you will create an OAuth application which will grant your program(s) authorization to call APIs.

Why API Tokens & OAuth Applications?

The reason we use API Tokens and OAuth applications is to separate end-user authentication and application authorization. By using API Tokens and OAuth applications you can achieve much greater control over the programmatic access granted to your cloud resources as well as scope the necessary access accordingly to avoid malicious use of APIs beyond the intended scope of the application.

You can learn about generating an API Token here.

Using API Tokens

Once you’ve generated an API Token you will use it to programmatically authorize access to APIs.

Before your application can begin calling APIs it must first make a POST request to the Cloud Services Platform (CSP) authorize API using your API Token passed with a content type of “application/x-www-form-urlencoded”. Here’s an example in curl:

curl --location --request POST 'https://console.cloud.vmware.com/csp/gateway/am/api/auth/api-tokens/authorize' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'refresh_token=dmDH3qSAuyljYajcvHz267Of4iVSN9VjiaxzEZ223qEaGdpe0vOqIASknYKv58JT'

The CSP authorize API call will return an access_token along with additional details associated with the API Token as follows:

{
    "id_token": "...",
    "token_type": "bearer",
    "expires_in": 1799,
    "scope": "openid group_ids group_names",
    "access_token": "...",
    "refresh_token": "..."
}

In the response above the access_token will be a character string which you’ll need to include as an HTTP header on all subsequent API calls using the key “csp-auth-token” as follows:

Content-Type: application/json
csp-auth-token: access_token_value

Also note, the access_token can be used in the API Explorer in the Developer Center on VMware Cloud on AWS.

Handling access_token Expiration

As part of the CSP authorize API you will receive an expires_in key indicating the number of seconds before the access_token will expire. After this expiration period subsequent calls to any VMware Cloud on AWS API will return the following error:

{
    "timestamp": "2020-01-02T17:11:01.223+0000",
    "status": 401,
    "error": "Unauthorized",
    "message": "Auth token is not valid",
    "path": "/vmc/api/orgs"
}

When an API call fails with the above error your script/program can request a new access_token using the refresh_token provided in the initial CSP authorize call (see above) and simply request a new access_token by re-issuing the authorize API using the provided refresh_token.