Logging In

To begin using the API, you request the system to create a Session object. In this request, you supply your credentials in an Authorization header of the form prescribed by the identity provider that your organization uses. The response includes an authorization token, which you must include in subsequent requests.

Every version of the VMware Cloud Director API supported by VMware Cloud Director has a login URL that a client can obtain by making an unauthenticated GET request to the api/versions URL. See Retrieve the Login URL and List of Supported API Versions. Because all other VMware Cloud Director API requests must be authenticated, any VMware Cloud Director API workflow must begin with a login request that creates a session and returns an authorization token. The token must be included in subsequent VMware Cloud Director API requests.

Prerequisites

Verify that the following conditions are met:

You know the type of identity provider that your organization uses. See Create a VMware Cloud Director API Session for more about identity providers, or ask your organization administrator.
You have the login credentials of a user with the predefined vApp Author role or another role that has an equivalent set of rights.
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 Managing an Organization.
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.

Procedure

Make an API versions request to VMware Cloud Director to obtain the VMware Cloud Director API login URL.
This request has the following form:
```
GET http://vcloud.example.com/api/versions
```
POST a request to the login URL to create a login session.
Depending on the type of identity provider your organization uses, the form of this request changes.
- For system administrators:
```
POST https://vcloud.example.com/cloudapi/1.0.0/sessions/provider
```
- For tenants:
```
POST https://vcloud.example.com/cloudapi/1.0.0/sessions
```
See Login Session Request and Response.
Examine the response.
A successful request returns an authorization token, which you must include in subsequent VMware Cloud Director API requests.

Example: Login Session Request and Response

To create a session object, you supply your credentials in an Authorization header of the form prescribed by the identity provider that your organization uses, then POST a request to the VMware Cloud Director API login URL. This request does not have a body. All the information required to create a session is included in the Authorization header. When using OAuth, the value of the X-VMWARE-VCLOUD-TOKEN-TYPE is Bearer and the constructed header must be in the following form.

Authorization: Bearer token

For more information and other examples of this request for all supported types of identity provider, see Create a VMware Cloud Director API Session.

toke

The Session response to a successful login request includes an X-VMWARE-VCLOUD-ACCESS-TOKEN header whose value is an encoded key that you can use, with the value of the X-VMWARE-VCLOUD-TOKEN-TYPE header, to construct an Authorization header to include in subsequent requests.

The Session response includes Link elements that reference the VMware Cloud Director API objects to which you have access rights. This example shows a response for a user named HelloUser who is a member of an organization named ExampleOrg.

Response:

200 OK
X-VMWARE-VCLOUD-ACCESS-TOKEN: cn9u.../6bM=
X-VMWARE-VCLOUD-TOKEN-TYPE: Bearer
Content-Type: application/vnd.vmware.vcloud.session+xml;version=30.0
...
<Session
   xmlns="http://www.vmware.com/vcloud/v1.5"
   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:
```
X-VMWARE-VCLOUD-ACCESS-TOKEN: token
X-VMWARE-VCLOUD-TOKEN-TYPE: type
```
Use the values of these headers to construct an Authorization header to use in subsequent VMware Cloud Director API requests. For example, if the value of the X-VMWARE-VCLOUD-TOKEN-TYPE is Bearer, then the constructed header would have this form:
```
Authorization Bearer token
```
If the Authorization header is missing from the request, the server returns HTTP response code 403.
If the credentials supplied in the Authorization header are invalid, the server returns HTTP response code 401.

Important: The authorization token expires after a configurable interval of client inactivity. The default interval is 30 minutes. After the token expires, you must log in again to obtain a new token. The system administrator can change this default.