Legacy vCloud API client applications that use Basic HTTP authentication must use the legacy vCloud API login workflow.

This workflow begins with a request that supplies user credentials in the form that Basic HTTP authentication requires. If successful, this request creates a login session and returns an x-vcloud-authorization header. This header or a vchs-authorization header must be included in each subsequent vCloud API request. For details about the vchs-authorization header, see Obtain an Authorization Token from the vCloud Air Identity Management Service.

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 instanceAttributes of the vCloud Air Compute Service to get the orgName and sessionUri you need to create the login request. See Retrieve Instance Attributes for a vCloud Air Compute Service Instance.

1

Create a login session.

POST a request to the sessionUri that includes your encoded vCloud Air credentials. See Example: Legacy Client 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 legacy client request to create a login session must supply the user's credentials as a MIME Base64 encoding, as specified in RFC 1421, of a string that has the following form:

username@orgName:password

username

The user name that you use to log in to vCloud Air, such as HelloUser@example.com.

orgName

The internal organization name, in the form of a UUID string, that identifies your tenant organization object to the vCloud Air Service Controller. Your orgName is the value of the orgName attribute in the instanceAttributes of the instance of the vCloud Air compute service to which you are logging in. See Retrieve Instance Attributes for a vCloud Air Compute Service Instance.

password

The password that you use to log in to vCloud Air.

In the following example, the encoded-credentials for a member of the organization with orgName c22ka7f1-4634-46a2-89c6-13150e6ec7bc and logged into vCloud Air as HelloUser@example.com using password Pa55w0rd would be the MIME Base64 encoding of this string:

HelloUser@example.com@c22ka7f1-4634-46a2-89c6-13150e6ec7bc:Pa55w0rd

Request:

POST https://vchs.example.com/api/compute/api/sessions 
Authorization: Basic encoded-credentials
Accept: application/*+xml;version=5.11

Response:

200 OK
x-vcloud-authorization: cn9uYmdugN8E2j96+5Lqrc3YBvFsEgDHXzyfJrJ/6bM=
Content-Type: application/vnd.vmware.vcloud.session+xml;version=5.11
...
<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-authorization token returned after your initial login to the vCloud Air Identity Management system has expired, the server returns HTTP response code 401. 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.

Expiration of the vchs-authorization token invalidates the x-vcloud-authorization token.