1.5
Table Of Contents
- vCloud API Programming Guide
- Contents
- vCloud API Programming Guide
- About the VMware vCloud API
- Hello vCloud: A Simplified RESTful Workflow
- Exploring a Cloud
- Provisioning an Organization with vApps, Templates, and Media
- Deploying and Operating vApps
- Summary of vCloud API vApp and Virtual Machine Operations Requests
- Create a vApp From a Template
- Compose a vApp From Existing Virtual Machines
- Recompose a vApp to Add or Remove Virtual Machines
- Operate a vApp
- Configuring vApps and Virtual Machines
- Retrieve the Configuration Links for a vApp
- Retrieve the Configuration Links for a Virtual Machine
- Retrieve or Update a Modifiable Section
- Update a vApp Network Configuration
- Update the NetworkConnectionSection of a Virtual Machine
- Retrieve or Modify the CPU Configuration of a Virtual Machine
- Retrieve or Modify the GuestCustomizationSection of a Virtual Machine
- Retrieve or Modify ProductSection Elements
- Retrieve or Modify Groups of Related Sections in a Virtual Machine
- Retrieve or Modify the Hard Disk Configuration of a Virtual Machine
- Creating, Provisioning, and Managing Organizations
- Summary of Administrative Requests
- Administrator Credentials and Privileges
- Organization Administration
- Network Administration
- vDC Administration
- Catalog Administration
- User and Group Administration
- Working With Roles and Rights
- Controlling Access to vApps and Catalogs
- Using vCloud API Extensions to Provision and Manage a Cloud
- Working With Object Metadata
- Using the Query Service
- Configuring and Using Blocking Tasks and Notifications
- XML Representations in the vCloud API
- Index
Create a Login 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.
Prerequisites
n
Verify that you know the login URL. See “Retrieve the Login URL and List of Supported API Versions,”
on page 42
n
Verify that you know the username and password of the system administrator or a member of one of the
organizations in the cloud.
System administrators must log in to the System organization. See “Administrator Credentials and
Privileges,” on page 111.
Procedure
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,” on page 44.
2 Examine the response.
The response code indicates whether the request succeeded, or how it failed.
n
If the authentication header is missing, the server returns HTTP response code 403.
n
If the credentials supplied in the authentication header are invalid, the server returns HTTP response
code 401.
n
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,” on page 165.
A Session object can be deleted by its owner or an administrator. After your Session expires or is deleted, you
are not authenticated.
Example: Create a Login Session
A request to create a login session must supply the user's credentials in the following form:
user
@
organization
:
password
n
user is the user's login name.
n
organization is the name of an organization of which the user is a member.
n
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
sessions URL is https://vcloud.example.com/api/sessions.
vCloud API Programming Guide
44 VMware, Inc.