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 vCloud API supported by vCloud Director has a login URL that a client can obtain by making an unauthenticated GET request to the api/versions URL. See Example: 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 creates a session and returns an authorization token in the value of the x-vcloud-authorization header. The token must be included in subsequent vCloud API requests.
Verify that the following conditions are met:
■
|
You know the type of identity provider that your organization uses. See Create a vCloud 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. |
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 vCloud API login URL. This request does not have a body. All the information required to create a session is included in the Authorization header. See Create a vCloud API Session for examples of this request for all supported types of identity provider.
The response includes a re-usable x-vcloud-authorization authorization token and a Session element whose Link elements reference the vCloud 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.
200 OK x-vcloud-authorization: cn9uYmdugN8E2j96+5Lqrc3YBvFsEgDHXzyfJrJ/6bM= Content-Type: application/vnd.vmware.vcloud.session+xml;version=5.6 ... <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.