vRA / vRO new 6.2 REST API sample

Its been a loooong minute since I posted!

I’ve never been a frequent poster, and I try to make my posts relevant, not just another entry on the google list for whatever thing you searched for that got you here today.  I was tasked with learning this vRealize Automation thing at work and until I had good things to share, well, I just wasn’t in the mood for sharing.  Maybe if I get itchy I’ll tell you in a future post how we moved all our users to a new Active Directory domain in the 1st half of 2015.

Back to VMWare though, the latest release of vRA has some yummy nouget-y goodness for us; REST APIs that actually make sense!  (technically, 6.0 had REST but noone could figure out how to call it…)

So I thought I’d show you how to form a request today!


For the following samples you’re going to need curl, and not some wussy I don’t encrypt my stuff version – no, you’re going to need the version that’s cross-compiled with SSL, so make sure you grab the right one!  I also used jq, which might just be my favorite new parsing tool for JSON.  It does everything I want out of a utility; its 100% command-line, its portable (zero install) with a minimal footprint, its open source, and it runs on Windows and Linux so all of the developers I work with can use it no matter what platform they’re on!

I saved both utilities in c:\curl, and put my .bat file and .json files there too.  Maybe not the best practice, but it’ll work for demonstration purposes.

Bearer Token

Just that title makes me think Magic: the Gathering must have some new card?

PulseOfTheAnimist Palanquin
Newest enchantment? Maybe an artifact?

Seriously, what is this Bearer Token thing?  Basically its an authentication token.  Like the old railway passes given to conducters and other VIPs, “admit bearer” is what would be printed on it.  If it were, you know, like a real token and not a series of bytes in a computer memory…

Ahhh, THAT Bearer Token!

First thing you’ll need is to get a bearer token and parse it.  You’ll need a .json file with your authentication details; the basic format is {“username”:”domain\\myusername“, “password”:”mypassword“, “tenant”:”vsphere.local”}.  Fill in your username, password, and if you’re not using the default, tenant, save it to c:\curl\HELOTOKEN.json and you’re good to go.  Use the following curl command to submit your request:

curl –insecure -H “Accept: application/json” -H “Content-Type: application/json” –data @HELOTOKEN.json https://vra-fqdn/identity/api/tokens > identity.json

Please note I used –insecure because my vRA environment is still using self-signed SSL certs.  If you have actual SSL certs that will validate, please drop the –insecure option.  This command will drop a .json file named identity.json in the current folder (c:\curl if you’ve been following along), the file looks a little like this:


So it has an expiry, an id, and a tenant.  Take note of the expiry; bearer tokens are good for 24 hours, and whats not obvious is a user can only have one at a time; if you ask for a new bearer token, that invalidates all previous bearer tokens.  These two facts mean its very difficult to manually get and use a bearer token.  First three days I worked with this API I’d get into work in the morning, request a new bearer token, and spend the rest of the morning copy and pasting it into various .bat files I forgot referenced it!  Then right before lunch, I’d run a .bat file that I forgot requests a new bearer token as the first line, and spend the afternoon copy / pasting the bearer token again.  On day four, I figured out, what we want to do is extract that id in such a way that we can automatically use it in subsequent curl calls.  For this I rely on jq:

jq .id -r < identity.json > bearer.txt
<bearer.txt (
set /p btoken=

It looks scary with all those punctuation symbols but its actually quite simple, let’s break it down:

jq .id -r parse out the id field from the json.  Print it to stdout in raw mode (i.e. no surrounding quotes or symbols)

< identity.json use the previously generated identity.json file as input to jq

> bearer.txt output the parsed id field to a file bearer.txt

<bearer.txt ( use bearer.txt as the input file for the following command

set /p btoken= set the environment variable btoken to the input.  This is doing something a little funky; the /p normally means to prompt for the environment variable, but in this case since we provided a stdin pipe, the contents of bearer.txt will be used instead of prompting the user

Close the section using bearer.txt as input.  Seriously did I need to type this out for you?

To use the bearer token add the following HTTP Header to all future curl calls:

-H “Authorization: Bearer %btoken%”

Machine Request

There’s some fancy schmancy ways to figure out how to format a Machine Request, that’s a topic for a future post. Today I’ll show you the easy manual way first. Begin by requesting the catalog item you want from the vRA console and note the request ID. After the request has completed, you can use curl to look at the request with the following command

curl –insecure -H “Accept: application/json” -H “Authorization: Bearer %btoken%” https://vra-fqdn/catalog-service/api/consumer/resources/?$filter=request/requestNumber+eq+myReqNumber > myreqOutput.json

This will create a file myreqOutput.json with details of your request.  The item you care most about is the catalog ID which you will be able to find at .content.0.catalogItem.id  Note that ID, then request the entitled catalog item with the following:

curl –insecure -H “Accept: application/json” -H “Authorization: Bearer %btoken%” https://vra-fqdn/catalog-service/api/consumer/entitledCatalogItems/?$filter=id+eq+&#8217;catalogItemId‘ > catalogItem.json

This time, note the provider binding at .content.0.catalogItem.providerBinding.bindingId.  Also note the tenant ID specified here.

Now you have the information you need to format the machineRequest.json file:

“@type”: “CatalogItemRequest”,
“catalogItemRef”: {
“id”: “catalogItemId
“organization”: {
“tenantRef”: “vsphere.local”,
“subtenantRef”: “
“requestedFor”: “
“state”: “SUBMITTED”,
“requestNumber”: 0,
“requestData”: {
“entries”: [{
“key”: “provider-blueprintId”,
“value”: {
“type”: “string”,
“value”: “
“key”: “provider-VirtualMachine.Network0.NetworkProfileName”,
“value”: {
“type”: “string”,
“value”: “
Network Profile Name
“key”: “provider-Variable1”,
“value”: {
“type”: “string”,
“value”: “

Note the key: provider-name section above; this is how you specify any custom properties for the blueprint, I provided a couple samples above but what you put here will really depend on the blueprint configuration.  Basically just add provider- to the start of any custom property (or even VM property, see provider-VirtualMachine.Network0.NetworkProfileName above) to submit it with your request… which brings us to…

Submit a Request

The curl command to submit a request is:

curl -X POST –insecure -H “Content-Type: application/json” -H “Authorization: Bearer %btoken%” https://vra-fqdn/catalog-service/api/consumer/requests –data @machineRequest.json


That’s it for today!  Post a comment, what would you like to see next time, a more advanced end-to-end REST API call complete with status polling and ssh into the finished VM, or how my employer moved several hundred users from one Active Directory domain to a new one?

As always, follow @merlinjim on twitter to be notified when I write new articles!


I've been automating everything I can get my hands on since I was a wee lad, these days its mostly Office, UC4, or VMWare - but I have a strong interest in AI, microfluidics, and 3D printing when I'm not slaving for "da man"

Tagged with: , , , , , , ,
Posted in Automation, vRA

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 )

Twitter picture

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

Facebook photo

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

Google+ photo

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

Connecting to %s

Head Shot of Jim

Jim McCracken

Enter your email address to follow this blog and receive notifications of new posts by email.

Follow me on Twitter
Past Posts
Automate The Cloud pages
%d bloggers like this: