A successful login request to the vCloud Air Identity Management Service authenticates you to the system and returns an authorization token that you must include in all subsequent vCloud Air API requests. This token can also be used to authorize vCloud API requests.

The vCloud Air Identity Management Service requires you to use Basic HTTP authentication when logging in. A successful login to the Identity Management Service returns an authorization token that expires in 15 minutes. While this token is valid, you are authorized to make requests to all vCloud Air services. After the token has expired, you must log in to the vCloud Air Identity Management Service to renew it. For more information about how vCloud Air implements authentication and authorization for secure API access, see vCloud API 5.7 with vCloud Air Extensions Programmer's Guide.

Verify that you have met the conditions as described in Use the vCloud API with a vCloud Air Virtual Private Cloud OnDemand Instance.

1

Create a MIME Base64-encoding of your vCloud Air credentials.

These credentials have the following form:

username@orgName:password

username

The user name that you use to log in to vCloud Air, such as HelloUser@example.com.

orgName

The internal organization name, in the form of a UUID string, that identifies your vCloud Air tenant organization.

password

The password that you use to log in to vCloud Air.

For example, the credentials for a user named HelloUser@example.com who has the password Pa55w0rd and is a member of the organization with orgName 2418f672-8121-4fad-bf0d-6487e1c11ee2 would be the MIME Base64 encoding of this string:

HelloUser@example.com@2418f672-8121-4fad-bf0d-6487e1c11ee2:Pa55w0rd

2

Log in to the vCloud Air Identity Management Service.

See Example: Log In To the vCloud Air Identity Management Service.

3

Examine the response.

The response to a successful request includes an authorization token and a JSON object that lists your the service group IDs. See Example: Log In To the vCloud Air Identity Management Service.

Use a request of the following form, where the value of the encoded-credentials in the Authorization header is the encoded string you created in Step 1 :

Request:

POST https://vca.vmware.com/api/iam/login
Accept: application/json;version=5.7
Authorization: Basic encoded-credentials

The response code indicates whether the request succeeded, or how it failed.

A successful request returns HTTP response code 201 (Created), a vchs-authorization header whose value is your vCloud Air API authorization token, and a body that consists of a JSON object that lists your vCloud Air service group ID. You will need This ID when you request the list of service instances available to you. For details about the relationship between the service group ID and the user account, plans, and instances, see the vCloud API 5.7 with vCloud Air Extensions Programmer's Guide.

Response:

201 Created
...
Content-Type: application/json; version=5.7
vchs-authorization: eyJhbGciOiJSUzI1NiJ9.eyJq...
...
Body:
{"serviceGroupIds":["d6a2b8c4-6355-4264-b9d7-b26fla32d179"]}

If the Authorization header is missing, HTTP response code 403 is returned.

If the user account credentials supplied in the Authorization header are invalid, HTTP response code 401 is returned.

If the terms of service have not been accepted by that user account, HTTP response 412 is returned.

After saving the authorization token ( the value of the vchs-authorization header), complete the steps in Retrieve Instance Attributes for a vCloud Air Compute Service Instance.

Important

The vCloud Air Identity Management system's vchs-authorization token expires 15 minutes after its issue time, even when API clients are active. Client requests that present an invalid or expired authorization token return HTTP status code 401 (Unauthorized) and the client must re-authenticate to the vCloud Air Identity Management system and obtain a new token.