vCloud Director requires API requests to be authenticated. The first step in any RESTful workflow is to obtain an authentication token.

Every cloud has a login URL that a client can obtain by making an unauthenticated GET request to the vCloud Director api/versions URL. See Retrieve the Login URL and List of Supported API Versions. Because all other vCloud API requests must be authenticated, any vCloud API workflow must begin with a login request that supplies user credentials in the form that Basic HTTP authentication requires.

For information about how to create a login request and view the response, see Example: Login Request and Response .

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 the following conditions are met:

You are a member of an organization in the cloud, and have permission to create and operate vApps.

Your organization contains at least one vDC and one network. For more information about setting up an organization to support the Hello vCloud workflow, see Creating and Managing Organizations.

Your organization contains a catalog in which at least one vApp template is available. For more information about adding a vApp template to a catalog, see Provisioning an Organization.

1

Make an API versions request to vCloud Director to obtain the login URL for the REST API.

2

Use the login URL to create a login session.

POST a request to this URL that includes your username, password, and organization name in a MIME Base64 encoding. See Example: Login Request and Response .

3

Examine the response.

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

A successful login request returns an authentication 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 a subset of objects in the cloud. If you log in as a system administrator or organization administrator, this list includes multiple links. See Example: Create a Login Session Using the Integrated Identity Provider. Otherwise, the list typically includes a link of type application/vnd.vmware.vcloud.orgList+xml, as shown in the response portion of Example: Login Request and Response . You can use this link to find out more about your organization and the objects it contains.

For more information about the other links in the Session element, see Create a Login Session Using the Integrated Identity Provider.

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.

Note

System administrators must log in to the System organization. See Administrator Credentials and Privileges. Because the System organization does not support some of the features demonstrated in the Hello vCloud workflow, you should try this example in another organization.

This example shows a login request and response for a user named HelloUser logging into an organization named ExampleOrg in 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=5.1

Response:

200 OK
x-vcloud-authorization: cn9uYmdugN8E2j96+5Lqrc3YBvFsEgDHXzyfJrJ/6bM=
Content-Type: application/vnd.vmware.vcloud.session+xml;version=5.1
...
<Session
   xmlns="http://www.vmware.com/vcloud/v2.0"
   user="HelloUser"
   org="ExampleOrg" 
   ... >
   <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 must be included in each subsequent vCloud API request.

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

If the credentials supplied in the authentication header are invalid, or if the token has expired, the server returns HTTP response code 401. The token expires after a configurable interval of client inactivity. The default is 30 minutes after the token is created. After the token expires, you must log in again to obtain a new token.