The vCloud API login mechanism authenticates a user and creates a Session object that contains the URLs from which that user can begin browsing. Users who authenticate to the integrated identity provider use basic HTTP authentication.

Note

This procedure assumes that you are logging in with credentials managed by the vCloud Director integrated identity provider. Users whose credentials are managed by a SAML identity provider must follow a different login workflow.

Verify that you know the login URL. See Retrieve the Login URL and List of Supported API Versions.

Verify that you are logging in as a user whose identity is managed by the vCloud Director integrated identity provider.

1

Use the login URL to authenticate to the cloud.

POST a request to this URL. The request must include your username, organization name, and password in a MIME Base64 encoding. See Example: Create a Login Session Using the Integrated Identity Provider.

2

Examine the response.

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

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

If the credentials supplied in the authentication header are invalid, the server returns HTTP response code 401.

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

x-vcloud-authorization: token

This header must be included in each subsequent vCloud API request.

The Session element returned from a successful login contains one or more URLs from which you can begin browsing.

The list of URLs in the Session object is based on the role and privileges of the authenticated user. A Session object expires after a configurable interval of client inactivity. To change the length of this client inactivity timeout, a system administrator can change the value of SessionTimeoutMinutes in the system's GeneralSettings. See Retrieve or Update System Settings.

A Session object can be deleted by its owner or an administrator. After your Session expires or is deleted, you are not authenticated.

A request to create a login session must supply the user's credentials in the following form:

user@organization:password

user is the user's login name.

organization is the name of an organization of which the user is a member.

password is the user's password.

These credentials must be supplied in a MIME Base64 encoding, as specified in RFC 1421.

This example shows a login request and response for a system administrator logging in to a cloud whose login URL is https://vcloud.example.com/api/sessions.

Request:

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

Response:

200 OK
x-vcloud-authorization: cn9uYmdugN8E2j96+5Lqrc3YBvFsEgDHXzyfJrJ/6bM=
Content-Type: application/vnd.vmware.vcloud.session+xml
...
<Session
   xmlns="http://www.vmware.com/vcloud/v1.5"
   user="sysadmin"
   org="System" 
   ... >
   <Link
      rel="down"
      type="application/vnd.vmware.vcloud.orgList+xml"
      href="https://vcloud.example.com/api/org"/>
   <Link
      rel="down"
      type="application/vnd.vmware.admin.vcloud+xml"
      href="https://vcloud.example.com/api/admin"/>
   <Link
      rel="down"
      type="application/vnd.vmware.admin.vmwExtension+xml"
      href="https://vcloud.example.com/api/admin/extension"/>
  <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>

This response includes the following link types:

orgList

A link to the list of organizations that you can access. See Retrieve a List of Organizations Accessible to You.

vcloud

A link to administrative objects and operations. See Creating and Managing Organizations

vmwExtension

A link to the vCloud API extensions, accessible to a system administrator. See Managing and Monitoring a Cloud.

queryList

A link to the set of typed queries you can run. See Using the Query Service.

entity

A link to the entity resolver. See Retrieve an Object as an Entity.