Before you can use the vCloud API to work with the an instance of the vCloud Air Compute Service, you must query the vCloud Air Service Controller to retrieve information about the instances available to you.

After you obtain a list of available vCloud Air Compute Service instances from the vCloud Air Service Controller, you identify the one that you want to use, then retrieve the instance attributes that you must use when making make a vCloud API request to that instance.

Verify that you have a valid authorization token from the vCloud Air Identity Management Service. See Obtain an Authorization Token from the vCloud Air Identity Management Service.

Important

The vCloud Air Identity Management system's vchs-authorization token expires 15 minutes after its issue time, even when API clients are active. Client requests that present an invalid or expired authorization token return HTTP status code 401 (Unauthorized) and the client must re-authenticate to the vCloud Air Identity Management system and obtain a new token.

1

Retrieve the list of service instances by querying the Service Controller component's /api/sc/instances API.

Use a request like this one, where token is the value of the vchs-authorization token returned when you logged in to the vCloud Air Identity Management Service.

GET https://vca.vmware.com/api/sc/instances
Accept application/json;version=5.7
Authorization Bearer token

A successful response returns HTTP response code 200 (OK). The response body is a JSON object named instances that contains all of the instances accessible to you. The instances object might have more than one instance.

{
  "instances": [
   {"link": [],
    "description": "Create ...",
    "region": "uk-slough-1-6.vchs.vmware.com",
    "instanceVersion": "1.0",
    "planId": "region:uk-slough-1-6.vchs.vmware.com:planID:c65d5821-aa97-4141-915a-7d7lak0a9d51",
    "serviceGroupId": "kal53la1-2113-489e-b0d0-71e96c7e546e",
    "apiUrl": "https://uk-slough-1-6.vchs.vmware.com/api/compute/api/org/a63d50ad-lak8-4398-ab48-930a93b37fbc",
    "dashboardUrl":"https://uk-slough-1-6.vchs.vmware.com/api/compute/compute/ui?orgName=2428lakf-139a-46f0-80da-596549a0015a&serviceInstanceId=a63d50ad-lak8-4398-ab48-930a93b37fbc",
    "instanceAttributes":"{
      \"orgName\":\"2428lakf-139a-46f0-80da-596549a0015a\",
      \"sessionUri\":\"https://uk-slough-1-6.vchs.vmware.com/api/compute/api/sessions\",
      \"apiVersionUri\":\"https://uk-slough-1-6.vchs.vmware.com/api/compute/api/versions\",
    }",
    "id": "a63d50ad-lak8-4398-ab48-930a93b37fbc",
    "name": "Virtual Private Cloud OnDemand"
   }
   {"link": [],
    "description": "Create ...",
    "region": "us-virginia-1-4.vchs.vmware.com",
    "instanceVersion": "1.0",
    "planId": "region:us-virginia-1-4.vchs.vmware.com:planID:c65d5821-aa97-4141-915a-7d7lak0a9d51",
    "serviceGroupId": "kal53la1-2113-489e-b0d0-71e96c7e546e",
    "apiUrl": "https://us-virginia-1-4.vchs.vmware.com/api/compute/api/org/c3f4f6e7-fd19-486e-a821-91d177675kal",
    "dashboardUrl":"https://us-virginia-1-4.vchs.vmware.com/api/compute/compute/ui?orgName=c22ka7f1-4634-46a2-89c6-13150e6ec7bc&serviceInstanceId=c3f4f6e7-fd19-486e-a821-91d177675kal",
    "instanceAttributes":"{
      \"orgName\":\"c22ka7f1-4634-46a2-89c6-13150e6ec7bc\",
      \"sessionUri\":\"https://us-virginia-1-4.vchs.vmware.com/api/compute/api/sessions\",
      \"apiVersionUri\":\"https://us-virginia-1-4.vchs.vmware.com/api/compute/api/versions\",
    }",
    "id": "c3f4f6e7-fd19-486e-a821-91d177675kal",
    "name": "Virtual Private Cloud OnDemand"
   }
...
  ]
}
2

In the instances object, locate the instanceAttributes for the Compute Service instance you want to access with the vCloud API.

Each instance has its own unique values for these attributes. The instances object contains an instanceAttributes object for every instance of every service available to you.

"instanceAttributes":"{
      \"orgName\":\"c22ka7f1-4634-46a2-89c6-13150e6ec7bc\",
      \"sessionUri\":\"https://us-virginia-1-4.vchs.vmware.com/api/compute/api/sessions\",
      \"apiVersionUri\":\"https://us-virginia-1-4.vchs.vmware.com/api/compute/api/versions\",
    }"
3

In the instanceAttributes object, locate the values for the orgName and sessionUri attributes.

The instanceAttributes object contains three attributes. Two of these attributes, highlighted in the example in Step 2, are required when making vCloud API requests:

orgName

An attribute whose system-generated value is an internal name, in the form of a UUID string, which identifies the instance's organization object to the vCloud Air Service Controller. You must use this system-generated value in the credentials to log in to the Compute Service API at that instance.

sessionUri

An attribute whose value is the URL to which a client can make a vCloud API request. (Ignore the similarly named apiUrl attribute. This attribute is part of the Service Controller model and is for internal use within the vCloud Air services model. )

The apiVersionUri attribute, also present in the instanceAttributes, provides the URL to which a client can make an unauthenticated request to retrieve a list of vCloud API versions that the instance supports. See API Versions.

4

Save the orgName and sessionUri attribute values.

Use the values from the orgName and sessionUri attributes to log in to the Compute Service. See Log In To the Compute Service in vCloud Air Virtual Private Cloud OnDemand