Accessing the vCloud Director API

I've been working on a vCloud Director environment recently and need to use the API for my current project.  Well, I'm not a big API guy, so this has been a good learning experience for me!  The first hurdle that I had to overcome was authentication, and since I didn't find that to be super well documented, I figure that I should put my notes up here.  So, here's how I get authenticated to vCloud Director's API via PowerShell (because, of course PowerShell!).

First things first, you've got to figure out what credentials you want to use.  The most basic way to authenticate is with a local account (rather than an LDAP account), but you need to append a scope to that account name to get logged in.  If the account is part of an Organization, you can use that Organization's name, but if it's a system administrator, you'll need to use "@system" instead.

Next, you'll need to Base64/UTF8 encode your credentials in order to pass them successfully to vCloud Director, and that string will need to follow a specific format: <user>@<scope>:<password>.  So, if my username is "administrator" and my password is "mySecretPassword" I would get my base64 string with this PowerShell command:

$base64Creds = [Convert]::toBase64String([System.Text.Encoding]::UTF8.GetBytes('administraotr@system:mySecretPassword'))

With the Base64 credentials, our next step is to construct an authentication request header that we can send to VCD.  That header needs two components, "Authorization" and "Accept".  Authorization contains your Base64 credentials (prefaced by the word Basic because we're using local authentication), and Accept tells VCD what you want to get back from it.

$header = @{Authorization = "Basic $base64Creds";Accept = "application/*;version=33.0"}

With the header constructed, we can submit that to VCD!

$vCD = "MyVCDServer.provider.local"
$results = invoke-webrequest -header $header -method post https://$vCD/api/sessions

Those $results contain an authentication token for our session that we can submit with future requests to actually do things.  To submit that token, we need to bake it into the headers of our future requests.  To make my life easier, I like to build that header out once and re-use it everywhere.  Note that I've changed the Accept in this header a bit; I've told it that I want JSON formatted returns instead of the XML formatted returns that VCD defaults to.

$authHeader = @{Accept = "application/*+json;version=33.0";'x-vcloud-authorization' = $results.headers.'x-vcloud-authorization'}

With those headers built, I am now ready to make actual API calls to my VCD server!  For example, if I want to get a list of the organizations in VCD, I can do this:

$results = invoke-webrequest https://$vCD/api/org -header $authHeader

I can parse those results into a nice PowerShell object like this:

$results.rawcontent -split "`n"  | select -skip 10 | convertfrom-json

Well, that's it for today!