Create a vCloud API Session

The vCloud API login mechanism authenticates a user and creates a Session object that contains the URLs from which that user can begin browsing objects in an organization. Users must submit their credentials in the form required by the identity provider that their organization specifies.

The vCloud API does not have a login request. To begin using the API, you request the system to create a Session object, supplying your credentials in an Authorization header of the form prescribed by the identity provider that your organization uses. The response includes a re-usable authorization token and a Session element whose Link elements reference the vCloud API objects to which you have access rights. vCloud Director supports several forms of authentication to the vCloud API.

■	OAuth authentication, as defined in RFC 6749 (http://tools.ietf.org/html/rfc6749). Users defined in an OAuth identity provider must acquire an OAuth token from that identity provider and include it in the request to create a vCloud API Session.
■	SAML (Security Assertion Markup Language) authentication, as defined in RFC 6595 (https://tools.ietf.org/html/rfc6595). Users defined in a SAML identity provider must acquire and process a security assertion from that identity provider and include the processed assertion and other attributes in the request to create a vCloud API Session.
■	Basic HTTP authentication, as specified in RFC 2617 (https://www.ietf.org/rfc/rfc2617.txt). LDAP users and local users are defined by the vCloud Director integrated identity provider, and must include credentials in the form required by Basic HTTP authentication in the request to create a vCloud API Session.

All organizations are created with implicit support for the vCloud Director integrated identity provider. Organizations can be updated to add support for a SAML identity provider.

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

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.

All requests to create a login session include a similar set of steps.

Procedure

Make an API versions request to retrieve the list of supported API versions and the login URL for each version.

The request has this form:

GET http://vcloud.example.com/api/versions

You do not need to be authenticated to make a versions request.

POST a request to the login URL, supplying your credentials in the request's Authorization header.

These requests have the following form:

POST https://vcloud.example.com/api/sessions 
Authorization: auth-type credentials
Accept: application/*;version=api-version

The value of auth-type specifies the authentication protocol you are using. Each authentication protocol has its own requirements for credentials and other attributes.

Basic	Specifies Basic HTTP authentication. Requires your user name, organization name, and password in a MIME Base64 encoding.
Bearer	Specifies OAuth authentication. Requires an OAuth token and your organization name.
Sign	Specifies SAML authentication. Requires a compressed, encoded SAML assertion and other attributes.

Examine the response to retrieve the authorization token and links to objects that you have rights to access.

A successful request returns a Session element, which includes an x-vcloud-authorization header. You must include the x-vcloud-authorization header in each subsequent vCloud API request.

Subtopics

Create a Session Using OAuth Authentication

Create a Session Using SAML Authentication

Create a Session Using Basic Authentication