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