VJ49 Cloud

Introduction

VMware Cloud Foundation Automation (VCFA) provides REST APIs that allow administrators and developers to interact with the platform programmatically.

These APIs can be used to manage organizations, projects, deployments, infrastructure resources and various platform capabilities.

Whether you are developing automation workflows, integrating third-party platforms or building custom solutions using VMware Aria Orchestrator (vRO), understanding VCFA REST APIs is an important skill.

Postman is a popular tool for exploring and testing REST APIs. It allows us to construct HTTP requests, configure authentication, inspect responses and understand how different API operations work.

With VCFA 9.0, the authentication process involves different API endpoints depending on the authentication domain and the organization context in which the operations need to be performed.

In this guide, we will explore the VCFA 9.0 authentication mechanism using Postman and demonstrate how to execute authenticated API requests.

The objective is to provide a practical reference that administrators and developers can follow to understand and experiment with VCFA REST APIs.

1. Prerequisites

Before getting started, ensure that you have the following:

• A running VMware Cloud Foundation Automation 9.0 environment.
• Access to the VCFA environment.
• A valid user account with the required permissions.
• Organization ID, if performing organization-specific operations.
• Postman installed on your workstation.

Note: The API operations available to a user depend on the assigned roles and permissions.

2. Understanding VCFA Terminology

Before exploring the authentication process, let’s understand a few concepts used throughout this guide.

2.1 Tenant

A tenant represents an organization within the VCFA environment.

Organizations provide logical separation for users, projects, resources and permissions.

Each organization has a unique Organization ID, which can be used when performing API operations in the context of a specific organization.

2.2 Provider

The provider represents the platform-level administration scope.

Provider administrators manage the overall VCFA environment and have access to provider-level management capabilities based on their assigned permissions.

2.3 System Authentication Domain

System is a special authentication domain used for provider-level authentication in the authentication flow demonstrated in this guide.

When the authentication domain is System, VCFA uses the provider login endpoint.

For authentication domains other than System, the regular tenant login endpoint is used.

2.4 Organization ID

An Organization ID uniquely identifies an organization within the VCFA environment.

When a provider administrator needs to perform operations in a specific organization, the Organization ID is supplied as part of the tenant authentication context.

2.5 Access Token

Authentication is required to establish the identity of a user or application before accessing protected APIs.

REST APIs can support different authentication mechanisms depending on the API service and endpoint.

Some commonly used authentication mechanisms include:

• Basic Authentication: Uses a username and password encoded using Base64.
• Bearer Authentication: Uses an access token issued after successful authentication.

The authentication mechanism must be configured according to the requirements of the API being invoked.

For example, in VCFA 9.0:

• Basic Authentication is used when requesting a session through the login APIs.
• Bearer Authentication is used when accessing APIs using an already generated access token.

For Bearer Authentication, the request header is configured as:

Authorization: Bearer <access_token>

VCFA validates the supplied authentication credentials or token, along with the applicable permissions, before processing the API request.

2.6 OpenID Connect (OIDC)

OpenID Connect (OIDC) is an identity authentication protocol built on top of OAuth 2.0.

It enables applications to establish identity through an identity provider.

In the provider-to-tenant authentication process covered in this guide, VCFA uses OIDC-related components to retrieve relying party information and generate a tenant-scoped access token.

2.7 Relying Party and Client ID

A Relying Party is an application that relies on an identity provider for authentication.

In our implementation, we identify the relying party named:

automation-relying-party

The associated Client ID is required when requesting a tenant-scoped access token.

3. Understanding VCFA 9.0 Authentication Flows

Based on the authentication mechanism explored in this guide, we will cover three scenarios.

Scenario 1: Regular Tenant Authentication

Authenticate using a user account belonging to an authentication domain other than System.

Scenario 2: Provider Authentication

Authenticate using a user account belonging to the System authentication domain.

Scenario 3: Provider Authentication with Tenant Context

Authenticate using a System-domain account and generate an access token scoped to a specific organization.

The third scenario involves additional authentication steps to retrieve the OIDC relying party Client ID and generate the tenant-scoped access token.

We will explore each scenario individually.

4. Preparing Postman

Before executing the VCFA REST APIs, open Postman and create a new collection named:

VCFA 9.0 REST API Guide

We will organize the API requests into separate folders based on their functionality.

For this guide, we will provide the complete API endpoint, required headers and request payload for each operation.

Readers can directly configure these details in Postman and execute the requests against their VCFA environment.

Note: Replace the example VCFA hostname, usernames, passwords, Organization IDs and tokens with the corresponding values from your environment.

5. Scenario 1 – Regular Tenant Authentication

In this scenario, we authenticate using a regular tenant user account.

The authentication domain must be different from System.

5.1 API Details

Request URL:

https://<VCFA-FQDN>/cloudapi/1.0.0/sessions

Replace <VCFA-FQDN> with your VCFA environment hostname.

5.2 Configure Authentication in Postman

1. Create a new POST request in Postman.
2. Enter the API endpoint.
3. Navigate to the Authorization tab.
4. Select Basic Auth from the Auth Type dropdown.
5. Enter the following credentials:

Important: The username must follow this format:

username@domain

For example, if the username is admin and the authentication domain is TenantA, enter: admin@TenantA

Postman automatically Base64-encodes the credentials and generates the Basic Authorization header.

5.3 Configure Request Headers

Navigate to the Headers tab and add the following header:

The API version shown above is an example. Use the API version supported by your VCFA environment.

5.4 Execute the Request

Click Send to execute the POST request.

Upon successful authentication, VCFA returns the access token in the response header:

x-vmware-vcloud-access-token: <access-token>

The response body contains session information, including the session idle timeout.

5.5 Capture the Access Token

Navigate to the Headers section of the Postman response.

Locate the following response header:

x-vmware-vcloud-access-token

Copy its value. We will use this token when executing subsequent tenant API requests.

For APIs requiring Bearer authentication, configure the Authorization header as follows:

Authorization: Bearer <access-token>

Expected Result: Successful authentication and retrieval of the tenant access token.

6. Scenario 2 – Provider Authentication

In this scenario, we authenticate using a provider account belonging to the System authentication domain.

Unlike regular tenant authentication, provider authentication uses a dedicated login endpoint.

6.1 API Details

Request URL:

https://<VCFA-FQDN>/cloudapi/1.0.0/sessions/provider

Replace <VCFA-FQDN> with your VCFA environment hostname.

6.2 Configure Authentication in Postman

1. Create a new POST request in Postman.
2. Enter the API endpoint.
3. Navigate to the Authorization tab.
4. Select Basic Auth from the Auth Type dropdown.
5. Enter the following credentials:

Important: The username must follow this format: username@System

For example, if the provider username is admin, enter: admin@System

Postman automatically Base64-encodes the credentials and generates the Basic Authorization header.

6.3 Configure Request Headers

Navigate to the Headers tab and add the following header:

The API version shown above is an example. Use the API version supported by your VCFA environment.

6.4 Execute the Request

Click Send to execute the POST request.

Upon successful authentication, VCFA returns the provider access token in the following response header:

x-vmware-vcloud-access-token: <access-token>

6.5 Capture the Provider Access Token

Navigate to the Headers section of the Postman response.

Locate the following response header:

x-vmware-vcloud-access-token

Copy its value. We will use this provider access token for subsequent provider-level API requests and, where required, for generating a tenant-scoped access token.

Expected Result: Successful provider authentication and retrieval of the provider access token.

At this stage, we have successfully authenticated using the System authentication domain.

If we need to perform operations within a specific organization, we must continue with the next authentication scenario.

7. Scenario 3 – Provider Authentication with Tenant Impersonation

In this scenario, a provider administrator authenticates using the System authentication domain and obtains an access token for a specific organization.

For example, consider a VCFA environment with multiple organizations:

• Engineering
• Finance
• Human Resources

If a provider administrator needs to execute API operations within the Engineering organization, the corresponding Organization ID must be provided during the tenant-scoped token generation process.

This authentication flow involves three steps.

7.1 Step 1 – Provider Login

First, execute the provider login API described in Section 6.

Upon successful authentication, copy the provider access token from the response header:

x-vmware-vcloud-access-token

We will use this token in the subsequent API requests.

7.2 Step 2 – Retrieve OIDC Relying Party Details

Before generating a tenant-scoped access token, we need to retrieve the OIDC relying party Client ID.

VCFA provides an API to retrieve the configured relying party information.

API Details

Request URL:

https://<VCFA-FQDN>/cloudapi/1.0.0/openIdProvider/relyingParties

Replace <VCFA-FQDN> with your VCFA environment hostname.

Configure Authentication in Postman

1. Create a new GET request.
2. Enter the API endpoint.
3. Navigate to the Authorization tab.
4. Select Bearer Token from the Auth Type dropdown.
5. Paste the provider access token obtained in the previous step into the Token field.

Request Headers

Navigate to the Headers tab and add:

Use the API version supported by your environment.

Execute the Request

Click Send.

The response contains a collection of relying party configurations.

Identify the entry where the clientName is: automation-relying-party

automation-relying-party

For example, the response entry may look like this:

{
  "clientName": "automation-relying-party",
  "clientId": "<client-id>"
}

Copy the corresponding clientId. We will use it in the next authentication request.

7.3 Step 3 – Generate a Tenant-Scoped Access Token

Now that we have the provider access token and relying party Client ID, we can request an access token for the target organization.

API Details

Request URL:

https://<VCFA-FQDN>/oidc/oauth2/token

Replace <VCFA-FQDN> with your VCFA environment hostname.

Configure Request Headers

Navigate to the Headers tab and add the following headers:

Replace <Organization-ID> with the ID of the target organization.

For example:

urn:vcloud:org:123456

Configure Request Body

1. Navigate to the Body tab.
2. Select x-www-form-urlencoded.
3. Add the following parameters:

Understanding the Request Parameters

• grant_type: Specifies the JWT Bearer Grant authentication mechanism.
• scope: Specifies the requested access scopes.
• assertion: Contains the provider access token used as the bearer assertion.
• client_id: Identifies the relying party application.

The x-vmware-vcloud-tenant-context header identifies the target organization for which the token is requested.

Execute the Request

Click Send to execute the POST request.

Upon successful authentication, VCFA returns an OAuth token response containing the access_token field.

For example:

{
  "access_token": "<tenant-access-token>",
  "token_type": "Bearer"
}

The above is an illustrative response. Refer to the actual response returned by your VCFA environment for all available attributes.

Copy the value of access_token. This is the tenant-scoped access token.

7.4 Using the Tenant-Scoped Access Token

We can now use the generated access token to execute API operations within the target organization’s context.

For subsequent API requests:

1. Create a new request in Postman.
2. Enter the required API endpoint.
3. Navigate to the Authorization tab.
4. Select Bearer Token.
5. Paste the tenant-scoped access token into the Token field.
6. Configure any additional headers or request body required by the API.
7. Click Send.

VCFA will process the request according to the token’s organization context and the permissions associated with the authenticated user.

Expected Result: Successful generation of a tenant-scoped access token that can be used for supported API operations within the selected organization.

8. Authentication Flow Summary

In the previous sections, we explored three authentication scenarios for VMware Cloud Foundation Automation (VCFA) 9.0 using Postman.

The authentication flow depends on the authentication domain and the organization context required for the API operation.

Key takeaways:

• Use regular tenant authentication for operations within the authenticated tenant context.
• Use provider authentication for operations that require provider-level access.
• Use the OIDC flow when provider authentication needs to obtain an access token scoped to a specific organization.
• The operations available to a token depend on the permissions assigned to the authenticated account.

With these authentication flows understood, let’s move on to a practical example of using an access token to execute a VCFA API operation.

9. Executing a VCFA API Operation – Get All Deployments

Now that we have obtained an access token, let’s use it to retrieve the deployments available to the authenticated user.

For this example, we will use the Get Deployments API operation, which retrieves a list of deployments from VCFA.

API Details

Postman Configuration

Step 1: Create a GET request

Create a new request in Postman and select the GET method.

Enter the following URL:

https://<VCFA-FQDN>/deployment/api/deployments

Step 2: Configure Authentication

1. Open the Authorization tab.
2. Select Bearer Token as the authentication type.
3. Paste the access token obtained from one of the authentication scenarios covered earlier.

Step 3: Configure Headers

Under the Headers tab, add the following header:

Step 4: Send the Request

Click Send to execute the API request.

Expected Response

A successful request returns an HTTP 200 OK response containing a paginated list of deployments.

The response provides deployment information that can be used to identify and inspect deployments available to the authenticated user.

Understanding the API Response

Review the response body to understand the deployment attributes returned by the API. The available information can be used for further processing, filtering and automation.

Exploring Other VCFA APIs

This example demonstrates the basic approach to executing a VCFA API operation using Postman and an authenticated access token.

VCFA provides many additional APIs for managing deployments, catalog items, projects, infrastructure resources and other platform capabilities.

Instead of documenting every available operation in this article, refer to the official API references for detailed information about supported endpoints, request parameters, payloads and responses.

Useful references:

• Broadcom Developer Documentation:
  • https://developer.broadcom.com/
  • https://techdocs.broadcom.com/us/en/vmware-cis/vcf/vcf-9-0-and-later/9-1/administration-sdks-cli-and-tools/about-the-vcf-automation-api/what-are-the-automation-apis-and-how-do-i-use-them_1.html
• VCFA API Documentation: Refer to the API documentation available in your VCFA environment, where applicable.

The API documentation can be used to identify the required operation, understand its parameters and construct additional Postman requests.

Conclusion

In this guide, we explored how to authenticate with VMware Cloud Foundation Automation (VCFA) 9.0 REST APIs using Postman.

We covered regular tenant authentication, provider authentication and provider authentication with a specific organization context using OIDC.

We also demonstrated how to use an authenticated access token to execute a practical API operation and retrieve deployment information.

Understanding these authentication mechanisms and the basic structure of API requests provides a foundation for working with other VCFA services.

In upcoming articles, we will explore how to consume VCFA REST APIs using VMware Aria Orchestrator (vRO) and JavaScript to build reusable infrastructure automation solutions.

If you have any questions, thoughts, or just want to geek out over Aria Automation/VCF Automation, feel free to ping me on LinkedIn or drop me an email at jagadeeshvuppala1996@gmail.com. I’m always happy to help!