API Information

About the vCD API

The VMware vCloud Director (vCD) software used by Expedient Enterprise Cloud (EEC) offers a full REST API interface for use in your programming language of choice.

The full VMware API documentation can be found here.

Please refer to our Postman collection that includes preconfigured environment variables and several useful examples of how to utilize the API for common tasks. https://apidocs.expedient.cloud

Please read the following sections of this article for important information on supported API versions and how to authenticate to the API.

Changes to the API authentication process

In order to interact with your EEC environment via the API you will first need to authenticate to the API with a user account that has permissions to log into your EEC environment. If you have been using the vCD API for a while, the traditional way to make authenticated API requests was the /api/sessions endpoint and the x-vcloud-authorization header. Beginning in API version 36.1 (vCD 10.3.1), a new OAuth-based authentication mechanism was introduced to replace the legacy x-vcloud-authorization authentication. For a time, some API versions will support both authentication methods in order to provide time for people to become familiar with the new authentication method and update their code that interacts with the API. Please note that, as vCD continues to be updated, the older API versions that support the /api/sessions authentication method will be phased out so it is important to begin using the OAuth authentication method now.

Authenticating to the API

With the new OAuth authentication method, you must first create a token for your user account within vCD. For information on how to create an API token for a user please refer to Setting Up an API Access Token.

Once you have created an API access token, that “refresh_token” will be used to authenticate against the /oauth/tenant/{tenant name}/token endpoint to receive an access token for your API session (replace {tenant name} with your vCD organization name. You can find this in the URL bar when logged into the EEC portal). When you POST that “refresh_token” to the OAuth token endpoint the request will return an “access_token” that is used as a bearer token Authentication header in any subsequent requests to the API. 

Please refer to the Expedient Postman collection for examples of how this process is done in action. Fill in the environment variables for tenantName and refreshToken and the login request example will automatically store the returned value as the accessToken environment variable and populate it as the bearer token authentication header.

Supported API versions

Every version of vCD supports a number of API versions to add new features while maintaining backwards compatibility. If your API request is set to use an API version that the Expedient vCD servers do not support, the request will fail. To find which API versions the Expedient vCD servers currently support, you can query the /api/versions endpoint. If you are utilizing the Expedient postman collection, the Configure Accept Header request will automatically set the newest version in your environment variables.

The /api/versions endpoint will return the list of supported vCD API versions. Please note that some older API versions may still be supported but are listed as deprecated. If you are using an API version listed as deprecated it is important that you update your code, as that API version may be removed in future updates.

The following table illustrates the currently supported API versions on the vCD 10.4 version that Expedient currently uses, as well as the API versions that will be supported when Expedient moves to vCD 10.5 in the future. The table also illustrates the changes in supported authentication mechanisms between the different versions of the API.