Tech Reference: VMware Cloud - Intro to the API

Introduction

This document provides you with guidance on how to use the API with VMware Cloud on AWS (VMC).

There are several prerequisites and considerations that you must be aware of before you can start using the API for automation or scripting purposes.

Refer to the table below for a summary of the use cases, considerations, and other details to understand whether the API will address your needs.

Note in this document, text between double curly braces {{ }} and/or italics indicates a field that should be replaced with data specific to your environment. For example {{sddc_id}} would be replaced with the value of your SDDC ID, without the braces: e.g. fc80ee22-95aa-48be-92e1-e7b68b8e551e

Summary and Considerations

API Token Creation

Individual Account API Token

An API token (also known as a refresh token) is a key that is assigned to an individual account that is used to authenticate to the service via API and generate an access token which can then be used to make API calls to the Org.

Follow the steps below to create an API token:

1. Log into your account and go to the My Account page in the console and select My Account under User Settings. The My Account page is found under your Username in the top right-hand of the screen.
2. Go to the API Tokens tab on that page, and then select GENERATE TOKEN to create a new API token.

Note - Multiple tokens can exist simultaneously, each token has its own set of Organization and Service roles that determines what actions the user of the token will be authorized to perform. The CSP roles for VMC can be found on the product documentation page. Note that it is possible to grant roles for multiple CSP services (such as vRealize Log Insight) with the same token.

Important - Once the API token is generated, copy and store the token securely. It cannot be retrieved again, and it should be protected like a password, since it provides access based on the roles assigned to it.

The default lifetime of an API token is 6 months, but it can be set to a shorter or longer period, depending on your requirements and organization policies. It is also possible to manually revoke an API token before its expiration date.

OAuth App

For API use that is not associated with an individual, such as automation solutions, it is best not to use an API token associated with an individual account, in case that individual is not available when the token expires, they change roles or leave the organization, which can affect the services using that token. Instead,  the Organization owner can create an OAuth App that consists of both an App ID and App Secret to provide access to the API. OAuth apps act as entities in Server-to-server interactions and can be used in multiple organizations. While only the user who created an API token can manage it, the owner of the OAuth app is the organization in which it was created and it can be managed by users who are organization owners or organization members with a Developer role.

There are two distinct steps to creating an OAuth App: Create the App, and then assign the App to the Org. To create a new App, follow the steps below:

1. Log in to the CSP, click on your username in the top right-hand part of the screen and then select View Organization.
2. Click on the OAuth Apps tab in that top level page (and not on OAuth Apps in the left-hand menu, which is used for associating existing OAuth Apps with the Org).
3. Click Create App, and select Server to server app, then continue:

Create the App

1. Define App Name, App Description, Access Token TTL (the recommended token lifetime is 30 minutes. There is no way to revoke an access token once it is authorized, so avoid extending this time beyond what is necessary) and define the required Organization + individual Service Roles for the App.
2. Click Create. Note that All Roles provides unlimited access to all services and actions in the Organization and should be used with caution. Only the services and roles required should be granted to the App.
3. Download/copy the App ID & App Secret.

Note - It is not possible to access the App Secret after this screen. However, the App ID can be accessed, and a new App Secret can be generated for the App. Other App properties can also be edited post creation.

Add the App to the Org

You can do this in two ways:

• Select Add when you are creating the App, after the App ID and App Secret have been copied and stored, which will add it to the current Org.
• Navigate to the OAuth Apps page through the left-hand menu on the View Organization page. The latter is the only option when adding an App created in a different Org, select Add App and find the App in the Org where it was created (Note - the user performing this action must have appropriate access to both Orgs).

Requesting an Access Token Using an API (user) Token

An API token cannot be used directly to make API calls. Instead, it must be used to generate an access token through the CSP API:

Request:

POST https://console.cloud.vmware.com/csp/gateway/am/api/auth/api-tokens/authorize

Content-Type: x-www-form-urlencoded

Key: refresh_token; value: {{API token}}

Curl example:

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d 'refresh_token={{API Token}}' https://console.cloud.vmware.com/csp/gateway/am/api/auth/api-tokens/authorize

A successful response to this API is an HTTP 200 OK, and a JSON object that contains multiple items, including the expiry (in seconds from the time of response) of the token and the token itself. Copy the value of the key called “access_token” without the surrounding quotes. This key will be used for authenticating VMware Cloud on AWS API requests. Access tokens requested with an API token have a lifetime of 30 minutes, and there is no way to revoke an access token once it is issued. They will remain valid until their expiration time even if the API token used to request it is revoked.

Another option is to use a script in the Tests tab in Postman to assign the access token to a global variable, which can be automatically substituted into API calls by using the text {{access_token}}. An example of how to set the variable is by placing the following code in the Tests section of this authentication request:

var jsonData = JSON.parse(responseBody);

pm.globals.set("access_token", jsonData.access_token);

Requesting an Access Token using an OAuth App

POST https://console.cloud.vmware.com/csp/gateway/am/api/auth/authorize

Content-Type: x-www-form-urlencoded

Basic Auth

Username: {{App Name}}

Password: {{App Secret}}

Body:

Key: grant_type value: client_credentials

Note: Basic Authorization uses the format of an HTTP Header with key: Authorization and value of Basic + a space and the base64 encoded value of the AppID and AppSecret separated by a single colon: (“AppID:AppSecret”)

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -H 'Authorization: Basic {{base64 encoded AppID:AppSecret}}' -d 'grant_type=client_credentials' https://console.cloud.vmware.com/csp/gateway/am/api/auth/authorize

A successful response to this API is an HTTP 200 OK, and a JSON object that contains multiple items, including the expiry (in seconds from the time of response) of the token, and the access token itself. Copy the value of the key called “access_token” without the surrounding quotes. This key will be used for authenticating VMware Cloud on AWS API requests.

Another option is to use a script in the Tests tab in Postman to assign the access_token to a global variable, which can be automatically substituted into API calls by using the text {{access_token}}. An example of how to set the variable is by placing the following code in the Tests section of this authentication request:

var jsonData = JSON.parse(responseBody);

pm.globals.set("access_token", jsonData.access_token);

Determining the API Endpoints for an SDDC

There are multiple API Endpoints for VMware Cloud on AWS, depending on the service being addressed.

Most services use a common Endpoint for all Organizations, such as the CSP: https://console.cloud.vmware.com/csp/gateway/

And for VMware Cloud on AWS, you must include your Org ID and SDDC ID in the path:

https://vmc.vmware.com/vmc/api/orgs/{{org_id}}/sddcs/{{sddc_id}}

With NSX-T, since each SDDC has its own instance of NSX, the API Endpoint is specific to the SDDC. In fact there are 2 different Endpoint options. The first is the “reverse-proxy” which is Internet-accessible, going through the VMware Cloud Reverse Proxy service in the AWS Oregon region. The second is the local NSX Manager endpoint in the SDDC, which requires private network connectivity to the SDDC (such as VPN or AWS Direct Connect.)

The easiest way to find the URL for the NSX Endpoints are to go to the SDDC’s Settings tab in the CSP, and copy the vCenter FQDN.

Example vCenter FQDN: https://vcenter.sddc-10-20-30-40.vmwarevmc.com/

Make note of the series of 4 numbers separated by dashes (10-20-30-40 in the above example), and then substitute the numbers for your SDDC in the following URL samples to get the Endpoint for your SDDC. For Public Endpoints, you will also need to include your Org ID and SDDC ID in the path:

Reverse-Proxy (Public) Endpoint:

Template URL format: https://nsx-{{10-20-30-40}}.rp.vmwarevmc.com/vmc/reverse-proxy/api/orgs/{{org_id}}/sddcs/{{sddc_id}}/sks-nsxt-manager/policy/api/v1/

Example final URL: https://nsx-8-32-221-10.rp.vmwarevmc.com/vmc/reverse-proxy/api/orgs/eaec1ad1-dbc2-4495-86d1-30aaaef62faf/sddcs/9ccfbb09-48f4-4480-9753-e6389b84cbf1/sks-nsxt-manager/policy/api/v1/

NSX Manager (Private) Endpoint:

Template URL format: https://nsxmanager.sddc-{{10-20-30-40}}.vmwarevmc.com/policy/api/v1/

Example final URL: https://nsxmanager.sddc-8-32-221-10.vmwarevmc.com/policy/api/v1/

Authenticating API Calls

  Once you have an access token, and know which Endpoint you are authenticating to, you will need to authenticate the API call for it to succeed.

Depending on the Endpoint, authentication is accomplished using one of two formats. With the public Endpoints, authentication consists of a header in the API request with the access token. This takes the format of an HTTP header with a key of csp-auth-token and a value of the access token obtained from one of the authentication requests above.

In Postman this would be set up as in the image below:

In curl, use the following format. Substitute the sample API URL for the one you are using.

curl -X GET -H 'Content-Type: application/json' -H 'csp-auth-token: {{access_token}}' https://vmc.vmware.com/vmc/api/orgs/{{org_id}}/sddcs/{{sddc_id}}

To authenticate to the local NSX Manager Endpoint, a different authentication method is used. Instead of including the access token with the csp-auth-token header, it must be sent as HTTP Authorization with Bearer token.

In Postman this would be set up as in the image below:

In curl, use the following format. Substitute the sample API URL for the one you are using.

curl -X GET -H 'Content-Type: application/json' -H 'Authorization: Bearer {{access_token}}' https://nsxmanager.sddc-10-20-30-40.vmwarevmc.com/policy/api/v1/infra/tier-1s/cgw/segments/test_no_ip