All vCloud API requests to the vCloud Air Compute Service must include an Authorization header that supplies your user credentials in the form that the vCloud Air Compute Service requires.

The Hello vCloud workflow begins with a login request that supplies your user credentials and returns a Session object.

Verify that the following conditions are met.

You have vCloud Air login credentials that are valid for access to the vCloud Air Virtual Private Cloud OnDemand service option.

Note

If you want to run the Hello vCloud examples, you must have at least the set of rights associated with the vCloud Air End User role, and your organization must contain at least one VDC that has at least one network. Your organization must also contain a catalog in which at least one vApp template is available. For information about creating VDCs and networks, see Administering a Tenant Organization. For information about adding a vApp template to a catalog, see Provisioning an Organization.

You have retrieved the following information from vCloud Air.

The value of the vchs-authorization header returned in the response to your initial login to the vCloud Air IAM service.

The instanceAttributes of an instance of the vCloud Air Compute Service, which contains the orgName and sessionUri you need to create a vCloud API login session.

1

Create a login session.

POST a request to the sessionUri that includes your encoded vCloud Air credentials. See Example: Log In To the vCloud Air Compute Service.

2

Examine the response.

The response code indicates whether the request succeeded, or how it failed.

A successful login request returns an authorization token that you can use in subsequent requests. It also returns a Session element, which contains one or more Link elements, each of which provides a URL that you can use to explore the objects accessible to you.

A request to log in to the vCloud API combines your vCloud Air authorization token with other information that you retrieved from vCloud Air, authenticates you to an instance of the vCloud Air Compute Service, and creates a vCloud API Session object. Before you can make this request, you must use the vCloud Air APPI to retrieve the following values:

vchs-auth-string

The value of the vchs-authorization header returned in the response to a vCloud Air API login request. This value is valid for 15 minutes after it is returned to you. See Obtain an Authorization Token from the vCloud Air Identity Management Service.

orgName

An attribute of an instance of the Compute Service. Its value is an internal organization name, in the form of a UUID string, which identifies your organization object to the vCloud Air Service Controller. See Retrieve Instance Attributes for a vCloud Air Compute Service Instance.

sessionUri

An attribute of an instance of the Compute Service. Its value is the login URL to which a client can make a login request to access the latest version of the vCloud API supported by a Compute Service instance. See Retrieve Instance Attributes for a vCloud Air Compute Service Instance.

This example request uses values obtained from the instanceAttributes object shown in Use the vCloud API with a vCloud Air Virtual Private Cloud OnDemand Instance:

The orgName attribute of the service instance has the value c22ka7f1-4634-46a2-89c6-13150e6ec7bc.

The sessionUri attribute of the service instance has the value https://vchs.example.com/api/compute/api/sessions.

Request:

POST https://vcloud.example.com/api/sessions 
Authorization: Bearer vchs-auth-string; org=c22ka7f1-4634-46a2-89c6-13150e6ec7bc
Accept: application/*+xml;version=9.0

Response:

200 OK
x-vcloud-authorization: cn9uYmdugN8E2j96+5Lqrc3YBvFsEgDHXzyfJrJ/6bM=
Content-Type: application/vnd.vmware.vcloud.session+xml;version=5.10
...
<Session
   xmlns="http://www.vmware.com/vcloud/v1.5"
   user="HelloUser@example.com"
   org="c22ka7f1-4634-46a2-89c6-13150e6ec7bc" 
   ... >
   <Link
      rel="down"
      type="application/vnd.vmware.vcloud.orgList+xml"
      href="https://vcloud.example.com/api/org/"/>
  <Link
      rel="down"
      type="application/vnd.vmware.vcloud.query.queryList+xml"
      href="https://vcloud.example.com/api/query" />
   <Link
      rel="entityResolver"
      type="application/vnd.vmware.vcloud.entity+xml"
      href="https://vcloud.example.com/api/entity/" />
</Session>

The response code indicates whether the request succeeded, or how it failed.

If the request is successful, the server returns HTTP response code 200 (OK) and headers that include an authorization header of the following form:

x-vcloud-authorization: token

This header or the vchs-authorization header must be included in each subsequent vCloud API request.

If the Authorization header is missing, the server returns HTTP response code 403.

If the credentials supplied in the Authorization header are invalid, or if the vchs-authorizationtoken has expired, the server returns HTTP response code 40 1.

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.