vCloud Air requires login requests to be authenticated. Begin the workflow with an authentication request to vCloud Air.

Your company has purchased Virtual Private Cloud or Dedicated Cloud capacity in different regions of vCloud Air via My VMware and obtained an Account Administrator login on vCloud Air (procured directly through My VMware).

Your Account Administrator has created at least one user account with credentials in vCloud Air.

You are a user assigned to a role that can access the API.

You are a user assigned to a role that can access your compute services.

As a vCloud Air client, you present your credentials one time to log in and view the list of your subscribed compute services in vCloud Air.

The Session element, which the API returns from a successful login, contains a link to the services for that vCloud Air account. The client invokes the service link and receives a list of services. Each service contains a serviceType, serviceId, and an href to the content for that service. The compute serviceType has one of the following values:

compute:vpc

compute:dedicatedcloud

The vCloud Air automated subscription system assigns the value of the serviceId attribute.

1

POST a request to this URL that includes your user name and password in a MIME Base64 encoding:

POST https://vchs.vmware.com/api/vchs/sessions

The initial POST requires that you enter the Authorization header with an encoded Base64 username:password value as shown:

Authorization: Basic <HelloUser@example.com:password>

Wherein HelloUser@example.com:password is encoded.

If the request is successful, the server returns the following items in the response:

Response Header: x-vchs-authorization:vchs-auth-token
<Session 
...>
   <Link
      rel="down"
      type="application/xml;class=vnd.vmware.vchs.servicelist"
      href="https://vchs.vmware.com/api/vchs/services" />
</Session>

HTTP response code 201 Created

A response that contains the x-vchs-authorization

A response with a Session element that contains a link of type application/xml;class=vnd.vmware.vchs.servicelist to get your list of subscribed compute services in vCloud Air

2

From the Session response, use the value from the servicelist link and issue a GET request to retrieve the list of services:

GET href="https://vchs.vmware.com/api/vchs/services"

In the request, include the vCloud Air authorization token:

x-vchs-authorization:vchs-auth-token

Include the x-vchs-authorization token in all subsequent API requests as a request header.

The returned response includes the list of services subscribed for your vCloud Air account. Each Service element in the list has the following format:

<Services 
...>
   <Service
      region="xs:string"
      serviceId="xs:string"
      serviceType="compute:type"
      type="application/xml;class=vnd.vmware.vchs.compute"
      href="https://vchs.vmware.com/api/vchs/compute/compute-uuid" />
</Services>

This example shows the two parts that are required for logging in to the Compute Service that you have subscribed to with vCloud Air. The first part of the example shows the request and response for HelloUser to log in to vCloud Air at the URL https://vchs.vmware.com/api/vchs/sessions In Request 1, the initial POST requires you enter the Authorization header with an encoded Base64 username:password value.

The second part shows the request and response for HelloUser to pass the authorization token to obtain the compute service list purchased for the user's company account. The service list contains one service for a Virtual Private Cloud subscription.

Request 1:

POST https://vchs.vmware.com/api/vchs/sessions
Authorization: Basic "dXNlcm5hbWVAb3JnOnBhc3N3b3JkCg=="
Accept: application/xml;version=5.6

Response 1:

201 Created
Response Header: x-vchs-authorization:f1c687e31731cc9a5820d233e46ef1dfa131cb45
...
 <Session
   type="application/xml;class=vnd.vmware.vchs.session"
   href="https://vchs.vmware.com/api/vchs/session"
   xmlns="http://www.vmware.com/vchs/v5.6"
   xmlns:tns=http://www.vmware.com/vchs/v5.6
   xmlns:xs=http://www.w3.org/2001/XMLSchema
   xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance>
   <Link
      rel="down"
      type="application/xml;class=vnd.vmware.vchs.servicelist"
      href="https://vchs.vmware.com/api/vchs/services" />
   <Link
      rel="remove"
      href="https://vchs.vmware.com/api/vchs/session" />
</Session>

Request 2:

GET https://vchs.vmware.com/api/vchs/services
x-vchs-authorization:f1c687e31731cc9a5820d233e46ef1dfa131cb45
Accept: application/xml;version=5.6

Response 2:

200 OK
<Services
   type="application/xml;class=vnd.vmware.vchs.servicelist"
   href="https://vchs.vmware.com/api/vchs/services" 
   ...>
   <Service
      region="US - Las Vegas"
      serviceId="example-1101-130711-1"
      serviceType="compute:vpc"
      type="application/xml;class=vnd.vmware.vchs.compute"
      href="https://vchs.vmware.com/api/vchs/compute/vchs-2" />
</Services>