Back in 2022 I wrote vRA 8 API getting started, two curl calls and you had a bearer token. Since then the product has been renamed twice (vRealize Automation → VMware Aria Automation → VCF Automation) and, more importantly for anyone with scripts in production, the authentication flow changed in VCF 9.x. Neither of the two calls from that post works against a 9.1 appliance.

This is the 9.1 version of the same post: the minimum you need to do before you can actually query the API, with curl.

What Changed Since vRA 8

The short version, before the steps:

vRA 8.xVCF Automation 9.1 (VM Apps org)
Refresh tokenPOST /csp/gateway/am/api/login?access_token with username/passwordGenerated in the UI (My Account > API Tokens), no programmatic call
Bearer tokenPOST /iaas/api/login with the refresh tokenPOST /tm/oauth/tenant/{tenant}/token, standard OAuth grant_type=refresh_token
Bearer lifetime~8 hours1 hour
Refresh token lifetime90 days90 days by default (configurable, at creation time only)
API docshttps://vra_url/automation-ui/api-docs/In-product API Help Center, plus developer.broadcom.com

The two things that break existing scripts:

  1. You cannot get a refresh token with username and password anymore. The docs are explicit: “As of VCF 9.0, the Identity Service API functionality has changed and is no longer used to obtain a refresh token programmatically.” The refresh token is now an API token you generate once in the UI and treat like a credential.
  2. There is a tenant in the URL now. VCF Automation 9 has a provider/tenant model. Everything that used to be vRA lives inside a VM Apps organization, and the token endpoint is scoped to that org name, so step zero is finding out what yours is called.

Step 0: Find Your VM Apps Tenant Name

Log into the Provider Management Portal (https://vcfa.domain.com, the admin account) and go to Organizations. Note two things:

  • The name of your VM Apps organization, if you upgraded from Aria Automation 8.x, this is the classic tenant that was created during migration (the docs use vcf-e2e-vidm as an example).
  • The FQDN of the appliance itself.

You need both for every call that follows.

Step 1: Generate an API Token (the New Refresh Token)

This is the part that moved from curl to the UI:

  1. Open the VCF Automation UI at https://vcfa.domain.com and switch the organization to your VM Apps tenant.
  2. Log in with a tenant account (it needs to be an org member with at least the user service role, an org_owner works fine).
  3. Click your name in the top-right corner and select My Account.
  4. Go to the API Tokens tab, click New, give the token a name, and click Create.
  5. Copy the token; it is shown once.

By default the token lives for 129,600 minutes (90 days). If you want a different lifespan, set it before creating the token under General Settings > Timeouts in the Provider Management Portal (0 means unlimited); the lifetime is baked in at creation and cannot be changed retroactively. To kill a token early, revoke it from the same UI or via DELETE /cloudapi/1.0.0/tokens/urn:vcloud:token:<token_id>.

Step 2: Exchange the API Token for an Access Token

This replaces the old POST /iaas/api/login. The endpoint is a standard OAuth token endpoint, scoped to your tenant:

curl -k --location --request POST 'https://vcfa.domain.com/tm/oauth/tenant/your-vm-apps-tenant/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'Accept: application/json' \
  --data-urlencode 'grant_type=refresh_token' \
  --data-urlencode 'refresh_token=YOUR_API_TOKEN'

The response contains the bearer token:

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "YOUR_API_TOKEN"
}

The access token expires after one hour, noticeably shorter than the ~8 hours you got from /iaas/api/login in 8.x, so long-running scripts should be prepared to re-run the exchange.

For scripting, the whole thing collapses into one line with jq:

ACCESS_TOKEN=$(curl -sk --request POST "https://$VCFA_HOST/tm/oauth/tenant/$VCFA_TENANT/token" \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept: application/json' \
  --data-urlencode 'grant_type=refresh_token' \
  --data-urlencode "refresh_token=$VCFA_API_TOKEN" | jq -r .access_token)

Step 3: Use It

The good news: once you have the access token, the API surface you know from vRA 8 is still there. The 9.1 programming guide tutorials use the same service endpoints (/iaas/api, /catalog/api, /deployment/api, /blueprint/api, /abx, the Orchestrator gateway) with a plain bearer header:

curl -sk "https://$VCFA_HOST/iaas/api/projects" \
  -H "Authorization: Bearer $ACCESS_TOKEN" | jq .

If a call comes back 403, verify what the account actually is inside the org. The docs still expose the CSP gateway for this (note the csp-auth-token header instead of Authorization):

# your org id
curl -sk "https://$VCFA_HOST/csp/gateway/am/api/loggedin/user/orgs" \
  -H "csp-auth-token: $ACCESS_TOKEN" | jq .

# org role: must be org_owner or org_member
curl -sk "https://$VCFA_HOST/csp/gateway/am/api/loggedin/user/orgs/$ORG_ID/roles" \
  -H "csp-auth-token: $ACCESS_TOKEN" | jq .

# service roles: must include at least "user"
curl -sk "https://$VCFA_HOST/csp/gateway/am/api/loggedin/user/orgs/$ORG_ID/service-roles" \
  -H "csp-auth-token: $ACCESS_TOKEN" | jq .

One caveat from Broadcom: scripts that authenticate against new VM Apps organizations (created in 9.x, not upgraded from 8.x) should use the VCF Automation Provider Management Access Control APIs rather than the CSP APIs, treat the CSP gateway as a compatibility surface, not a foundation for new tooling.

Where the API Docs Moved

The old in-product Swagger at https://vra_url/automation-ui/api-docs/ and the developer.vmware.com portal are both gone. In 9.1:

Also worth knowing before you port scripts from 8.x: the Pipelines/Code Stream APIs (/codestream/api/*), the CMX Kubernetes APIs, and the Migration Assessment APIs are removed in 9.1.

A Note on All Apps Organizations

Everything above covers the VM Apps organization, the classic vRA-shaped experience. The new All Apps side of VCF Automation 9 (the Cloud Director-heritage Tenant Manager) authenticates differently again: provider tokens come from POST /oauth/provider/token, and there is a session endpoint at /cloudapi/1.0.0/sessions/provider that does accept basic auth and returns the bearer in the x-vmware-vcloud-access-token response header. That API family deserves its own post; Christian Ferber has a good writeup linked below in the meantime.

References