Starting with VMware Cloud Director 10.3.1, you can generate and issue API access tokens. You are authenticated using your respective security best practices, including leveraging two-factor authorization, by using API access tokens, you can grant access for building automation against VMware Cloud Director.

Access tokens are artifacts that client applications use to make API requests on behalf of a user. Applications need access tokens for authentication. When an access token expires, to obtain access tokens, applications can use API tokens. API tokens do not expire.

When using access tokens, applications cannot perform certain tasks.

  • Change the user password
  • Perform user management tasks
  • Create more tokens
  • View or revoke other tokens

When accessing VMware Cloud Director by using an API access token, applications have only view rights for the following resources.

  • User
  • Group
  • Roles
  • Global roles
  • Rights bundles
Applications accessing VMware Cloud Director by using an API access token do not have the following rights.
  • Token: Manage
  • Token: Manage All

Prerequisites

Authenticating with an API token uses the "Refreshing an Access Token" standard as specified in the OAuth 2.0 RFC 6749 Section 6 to allow access to VMware Cloud Director as an OAuth application. The returned access token is the same as a VMware Cloud Director access token and client applications can use it to make subsequent API calls to VMware Cloud Director. To make an OAuth 2.0 RFC-compliant request, familiarize yourself with Request for Comments (RFC) 6749 Section 6 information about refreshing an access token.

Procedure

  1. In the top right corner of the navigation bar, click your user name, and select User preferences.
  2. Under the Access Tokens section, click New.
  3. Enter a name for the token, and click Create.
    The generated API token appears. You must copy the token because it appears only once. After you click OK, you cannot retrieve this token again, you can only revoke it.
  4. Make an OAuth 2.0 RFC-compliant request to the https://site.cloud.example.com/oauth/provider/token API endpoint.
    Key Value
    grant_type refresh_token
    refresh_token Generated_refresh_token
    The request returns an access token that applications can use to perform tasks in VMware Cloud Director. The token is valid even after the user logs out. When an access token expires, the application can obtain more access tokens by using the API token.

Example

Request: 
POST https://host_name/oauth/provider/token
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Content-Length: 71

grant_type=refresh_token&refresh_token=Generated_API_Token
Response: 
HTTP/1.1 200 OK
Content-Type: application/json

{
   "access_token":"Generated_Access_Token",
   "token_type":"Bearer",
   "expires_in":2592000,
   "refresh_token":null
}
Request using the generated access token: 
GET https://host_name/api/org
Accept: application/*+xml;version=36.1
Authorization: Bearer Generated_Access_Token
Response: 
HTTP/1.1 200 OK
Content-Type: application/vnd.vmware.vcloud.orglist+xml;version=36.1
X-VMWARE-VCLOUD-REQUEST-EXECUTION-TIME: 41

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OrgList
    xmlns="http://www.vmware.com/vcloud/v1.5"
    xmlns:vmext="http://www.vmware.com/vcloud/extension/v1.5"
    xmlns:ovf="http://schemas.dmtf.org/ovf/envelope/1"
    xmlns:vssd="http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_VirtualSystemSettingData"
    xmlns:common="http://schemas.dmtf.org/wbem/wscim/1/common"
    xmlns:rasd="http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_ResourceAllocationSettingData"
    xmlns:vmw="http://www.vmware.com/schema/ovf"
    xmlns:ovfenv="http://schemas.dmtf.org/ovf/environment/1"
    xmlns:ns9="http://www.vmware.com/vcloud/versions" href="https://host_name/api/org/" type="application/vnd.vmware.vcloud.orgList+xml">
    <Org href="https://host_name/api/org/a93c9db9-7471-3192-8d09-a8f7eeda85f9" type="application/vnd.vmware.vcloud.org+xml" name="System"/>
</OrgList>

What to do next

  • If you want tenants to be able to generate tokens, you must grant tenant roles the Manage user's own API token right.
  • By default, tenants see only the tokens they create. To allow organization administrators to see and revoke the tokens of the other tenant users in the organization, you must grant them the Manage all users' API tokens right. Administrators with the Manage all users' API tokens right can see only the names of other users' the tokens, not the tokens themselves.
  • To revoke any of your tokens, navigate to the User preferences page, and click the vertical ellipsis next to the token.
  • To revoke the tokens of other users, in the top navigation bar, under Administration, navigate to the access control settings for users. When selecting a specific user, you can also see their access tokens and revoke them.
  • If you need to identify events triggered by using an API access token, in the event log the following line appears in the additionalProperties section of an event.
    "currentContext.refreshTokenId": "<UUID_of_the_token_that_performed_the_action>",