vRA 8.1 – Quick Tip – API Authentication

Hello!

In this short blog post we will cover how to authenticate with the vRA 8.1 API.

For vRA 8.1 the steps to get your Bearer Token are twofold:

  1. First you need to retrieve your Refresh Token
  2. With that Refresh Token you can get your Bearer Token

This is apparently due to a ‘missing internal state’ according to the vRA 8.1 API Programming Guide found here.

Curious which API calls vRA 8.1 supports? Find more information below:

Let’s get started:

  1. Get your favourite REST API tool (Postman, Curl, …)
  2. Execute the following REST API call
    URL: https://<vRA8.1-URL>/csp/gateway/am/api/login?access_token
    Method: POST
    Headers: 'Content-Type: application/json'
    Body: {
    	"username": "username",
    	"password": "password",
    	"domain": "System Domain | AD Domain"
    }
    CURL Command:
    curl --location --request POST 'https://<vRA8.1-URL>/csp/gateway/am/api/login?access_token' \
    --header 'Content-Type: application/json' \
    --data-raw '{
    	"username": "username",
    	"password": "password",
    	"domain": "System Domain | AD Domain"
    }'
  3. If everything goes well you will retrieve the Refresh Token as shown below:
    Screenshot 2020-06-26 at 10.13.57
    Save the Refresh Token.
  4. Next up let’s retrieve our Bearer Token from the vRA 8.1 IaaS API:
    URL: https://<vRA8.1-URL>/iaas/api/login
    Method: POST
    Headers: 'Content-Type: application/json'
    Body: {
            "refreshToken": "refresh_token_here"
    }
    CURL Command:
    curl --location --request POST 'https://<vRA8.1-URL>/iaas/api/login' \
    --header 'Content-Type: application/json' \
    --data-raw '{
            "refreshToken": "refresh_token_here"
    }'
  5. The result will be the following:
    Screenshot 2020-06-26 at 10.21.46
    You now have a Bearer Token!

 

Let’s test it out.

With the following API Call we will retrieve deployment details and request the resource details of this deployment:

  1. Quickly lookup a Deployment and retrieve a Deployment ID from the vRA 8.1 UI:
    Screenshot 2020-06-26 at 11.35.02
  2. To retrieve this Deployment’s Details via API, perform the following:
    URL: https://<vRA8.1-URL>/deployment/api/deployments/<deployment-id>?expandResources=true
    Method: GET
    Headers: 'Content-Type: application/json' \
    'Authorization: Bearer <Bearer-Token>' \
    Body: 
    CURL Command:
    curl --location --request GET 'https://<vRA8.1-URL>/deployment/api/deployments/<deployment-id>?expandResources=true' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer <Bearer-Token>' \
    --data-raw ''
  3. This should result in similar output below:
    Screenshot 2020-06-26 at 11.32.21

Hopefully it helped!

11 thoughts on “vRA 8.1 – Quick Tip – API Authentication

    1. Hi Bryan!

      Thanks for visiting our Blog!
      Are you referring to the option ‘API Tokens’ as described here:? https://blogs.vmware.com/management/2019/04/generating-a-csp-api-token-cas.html

      When you’re running vRA 8 On Premise locally in your environment, it does not seem to offer the API Tokens as shown above. When you’re running vRA 8 as a service from within the VMware’s Cloud Services Platform, then you can generate API Tokens by going to the Cloud Services Portal. In this Portal you can generate an API Token for your account that should work with all the Cloud Services registered to your Cloud Services Portal (such as ‘Cloud Assembly’).
      Documentation on how to generate ‘API Token’ in VMware Cloud Services:
      https://docs.vmware.com/en/VMware-Cloud-services/services/Using-VMware-Cloud-Services/GUID-E2A3B1C1-E9AD-4B00-A6B6-88D31FCDDF7C.html

      So I believe this might have to do with vRA 8 On Prem vs vRA 8 as part of the VMware Cloud Services.

      Hope this helps! Have a nice day! 🙂

      Like

  1. Well that is a good explanation, thank you.
    Do you know if there is an API way to request the tokens with longer lifespans? DEVOPS plans to use Terraform or a similar tool to do the deployments and we would rather not hard code the ID and password in to those scripts, if you know what I mean. It looks like there is a way to do that in the web interface, but since we cant use that……

    Like

    1. Hi Bryan!

      The vRA 8 API Programming Guide provides the option to generate a ‘Refresh Token’ which is valid for 90 days. You can then later use this Refresh Token to authenticate further to the IaaS API if needed.
      Source: https://code.vmware.com/docs/10222/vrealize-automation-api-programming-guide–html-/GUID-AC1E4407-6139-412A-B4AA-1F102942EA94.html

      I believe this might also be the topic that’s explained here regarding Terraform & vRA 8:
      http://www.mobius.co.uk/getting-started-with-the-vrealize-automation-terraform-provider/#generating-an-api-token

      Basically if you are running vRA 8 On Premise, you need to work with the Refresh Tokens as highlighted earlier. Some more information can also be found here:
      https://github.com/vmware/terraform-provider-vra/blob/master/docs/getting_a_refresh_token.md

      Hope this helps & is what you’re looking for! Have a nice day!

      Like

    1. Hi Hari,

      Thanks for visiting our blog!
      Unfortunately I don’t know if this is possible in vRA 8. From the official documentation that I can find it seems not to be possible.

      In vRA 8 you have 2 tokens:
      – Refresh / API Token: Used to request a new Access / Bearer token, valid for 90 days.
      – Access Token: The old ‘Bearer’ token. Valid for 8 hours.

      In the official vRA 8 Programming Guide the following is mentioned:
      The access token is valid for eight hours. If the token times out, request it again.
      &&
      The API token is also known as the refresh token. It is valid for 90 days and can be used to generate
      a new access token when the access token expires.

      This leads me to believe that it’s not yet officially possible to change the duration of the Access Token. However maybe we need to change the way we use the API in vRA 8 by using the Refresh Token which is valid for 90 days which allows us to request new 8 hour Access Tokens.

      Official vRA 8 Programming Guide: https://vdc-download.vmware.com/vmwb-repository/dcr-public/4e3fc812-7817-4ad3-92af-766007499000/57daec73-115a-4e1b-ae43-9b2ced09dc9f/Programming-Guide.pdf

      Hope it helps a bit. If you do encounter an option to extend the duration of the Access Token, feel free to let us know 🙂

      Have a nice day!

      Like

  2. Hello
    thanks for your article. I would like to know how to revoke a token.
    I haven’t find anything in all the documentation I’ve read.
    Thanks

    Like

    1. Hi Amakou,

      Thanks for visiting our blog!
      I believe for vRealize Automation Cloud at VMware Cloud Services (https://console.cloud.vmware.com), it is possible to revoke an API Token (‘My Account’ – ‘API Tokens’ – ‘Revoke’).

      If you’re using vRealize Automation 8.X On Premises like me, it seems not to be possible to revoke an API Token. I also could not find it in the documentation nor in the API reference guides.
      Checking the VMware Cloud API references there seems to be an endpoint to revoke a refresh_token over api (/am/api/auth/revoke), however this page / endpoint is not existing in my local vRA 8.1 Lab (https://vra-81-url.com/csp/gateway/am/api/auth/revoke) nor is it documented at the Swagger UI of my local vRA 8.1 Lab.

      So I suppose that this functionality might not (yet) be publicly present (for us to consume) in the local / on premise edition of vRealize Automation 8.X.

      You can also reach out to the VMware vRA Community at: https://communities.vmware.com/t5/VMware-vRealize/ct-p/13000-home

      If you do find an option to revoke a token in vRA 8.X, don’t hesitate to share!

      Have a nice day!

      Like

  3. Hi, is there any way to block/reserve IP address for a particular VM via Rest API/script in vRA 8.1?
    My requirement is, vRA allocates one IP and assigned to VM nic card. Now manually I want to add 3 more IPs as alias to same VM’s NIC card. For that I need to reserve/allocate/block these 3 IPs in vRA internal IPAM so later on it don’t allocate three 3 IPs to subsequent virtual machine deployment.

    Like

    1. Hi,

      I believe currently that there is no public API call available to reserve IP addresses from vRA’s IPAM.
      However I investigated this a while back and I believe there was some kind of vRA internal API call to reserve & release IP Addresses from vRA’s IPAM.
      Please note that these internal vRA APIs are not officially publicly available and the usage of them is at your own risk. I also don’t know if vRA will allow you to reserve multiple IP addresses on the same network interface.

      Below you can find my notes from when I looked into it a while back, hope it can give you an idea:

      URL: [[vRA_FQDN]]/provisioning/uerp/resources/ip-addresses/[[vRA_SubnetRangeID]]_[[IP_Address_In_Subnet]]
      EXAMPLE_URL: https://myvra.lab.local/provisioning/uerp/resources/ip-addresses/94aacce1-b29d-4e4b-a41e-01efaab5d7df_192.168.1.230
      METHOD: PUT
      *NOTE: ‘ConnectedResourceLink’ property is required if IP address status is ALLOCATED
      BODY:
      1. Scenario 1: From IP Released to AVAILABLE (if the case)
      {
      “subnetRangeLink”: “/resources/subnet-ranges/94aacce1-b29d-4e4b-a41e-01efaab5d7df”,
      “connectedResourceLink”: “”,
      “ipAddress”: “192.168.1.230”,
      “ipAddressDecimalValue”: 168757214,
      “ipVersion”: “IPv4”,
      “ipAddressStatus”: “AVAILABLE”,
      “id”: “94093b4e-7ab5-4e76-8e08-f45f2148c213”,
      “customProperties”: {},
      “tenantLinks”: [
      “/tenants/organization/d5a30b86-8e67-47fe-9901-892891fds”,
      “/tenants/project/eec9396c434ba875-7f703c5265a6ad17”
      ],
      “documentVersion”: 7,
      “documentKind”: “com:vmware:photon:controller:model:resources:IPAddressService:IPAddressState”,
      “documentSelfLink”: “/resources/ip-addresses/94aacce1-b29d-4e4b-a41e-01efaab5d7df_192.168.1.230”,
      “documentUpdateTimeMicros”: 1603979288108000,
      “documentUpdateAction”: “PATCH”,
      “documentExpirationTimeMicros”: 0,
      “documentAuthPrincipalLink”: “/provisioning/auth/csp/users/vRA4U”
      }
      2. From IP Available IP to ALLOCATED
      {
      “subnetRangeLink”: “/resources/subnet-ranges/730a84d7-508b-49c3-96b5-46d921a7fc9c”,
      “connectedResourceLink”: “/resources/network-interfaces/b175cb19-0de0-3e20-9436-4e403c9bafa3”,
      “ipAddress”: “192.168.1.232”,
      “ipAddressDecimalValue”: 168756968,
      “ipVersion”: “IPv4”,
      “ipAddressStatus”: “ALLOCATED”,
      “id”: “730a84d7-508b-49c3-96b5-46d921a7fc9c”,
      “customProperties”: {},
      “tenantLinks”: [
      “/tenants/organization/d5a30b86-8e67-47fe-9901-892891fds”,
      “/tenants/project/eec9396c434ba875-7f703c5265a6ad17”
      ],
      “documentVersion”: 7,
      “documentKind”: “com:vmware:photon:controller:model:resources:IPAddressService:IPAddressState”,
      “documentSelfLink”: “/resources/ip-addresses/730a84d7-508b-49c3-96b5-46d921a7fc9c_192.168.1.232”,
      “documentUpdateTimeMicros”: 1603979288108000,
      “documentUpdateAction”: “PATCH”,
      “documentExpirationTimeMicros”: 0,
      “documentAuthPrincipalLink”: “/provisioning/auth/csp/users/vRA4U”
      }

      Feel free to try it out, can’t guarantee if it still works or if the information above 100% accurate since it was a while back. I never used it in production as the API call was internal to the product itself, might be difficult to follow / maintain with new releases and can be cumbersome to get all the properties of the body and url right etc.

      Have a nice day!

      Like

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s