Users defined in an organization that specifies an OAuth identity provider must acquire an OAuth token from the identity provider and include it in the request to create a Session.

Verify that you know the API login URL. See Example: 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 OAuth identity provider defined by your organization.

1

Acquire the OAuth token from your identity provider.

2

Use the login URL to authenticate to the vCloud API.

POST a request to this URL. The request must include an Authorization header that specifies Bearer as the authorization method, includes an OAuth token retrieved from your identity provider, and has the following attributes:

OAuth Authorization Header Attributes and Values

Attribute Name

Attribute Value

org

The name of your vCloud Director organization.

See Example: OAuth Login Request and Response.

3

Examine the response.

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 a header of the form:

x-vcloud-authorization: token

This header, including the token, must be included in each subsequent vCloud API request.

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.

A valid request returns a Session element. See Example: OAuth Login Request and Response

This example shows an OAuth login request and response for a user logging in to the Finance organization of a cloud whose API login URL is https://vcloud.example.com/api/sessions.

The following credentials are required:

OAuth-token

The token returned by your OAuth identity provider.

org

The name of your organization.

Request:

POST https://vcloud.example.com/api/sessions 
Authorization: Bearer OAuth-token; org=Finance
Accept: application/*;version=9.0

Response:

200 OK
x-vcloud-authorization: cn9uYmd...
...
<Session
   xmlns="http://www.vmware.com/vcloud/v1.5"
   userUrn="urn:vcloud:user:fe50b0b5-..." 
   user="bob"
   org="Finance" 
   ... >
  <Link
      rel="down"
      type="application/vnd.vmware.vcloud.org+xml"
      name="System"
      href="https://vcloud.example.com/api/org/5" />
  <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/" />
   <Link
      rel="down:extensibility"
      type="application/vnd.vmware.vcloud.apiextensibility+xml"
      href="https://vcloud.example.com/api/extensibility" />
</Session>

The response includes the re-usable x-vcloud-authorization header and these Link types:

org

A link to your organization. See Retrieve a List of Organizations Accessible to You.

queryList

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

entity

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

extensibility

A link to the extensibility framework entry point. See vCloud Director Extension Services.