Authenticating to the NSX-T API via PowerShell

I've had the chance to work on some NSX-T scripting lately, as we work to integrate some other solutions with the tool.  I don't have a ton of experience with API access, but I have been slowly learning... and one of the big hurdles that I had to overcome was just figuring out how to authenticate with the system!  So, that's where I'm going to start here.

First, let's talk about the basics of how authentication works when accessing the API.  To use Basic authentication, you need to put together your credentials in the format of "username:password" and pass them to NSX-T.  Since this is being passed through a web request and special characters could mess everything up, so you need to Base64 encode that authentication string.  Once you've got it encoded, you need to put that into the Headers of your requests so that NSX-T will know who you are.  So, let's look at how to actually do that process!

First, I'm going to prepare two variables.  One will have my credentials, and the other will be the URL of my NSX-T system:

$creds = Get-Credential -Message "NSX-T Administrative Credentials:"

$url = "https://myNSXTManager"

I wish that you could just pass a PowerShell credentials object directly to the invoke-webrequest cmdlet, but it's not that simple.  You need to Base64 encode those credentials (so that you're not transmitting all of the special characters that are in your password) and then put them into a specially formatted Header.  Here's how I do those steps!

$base64Creds = [Convert]::toBase64String([System.Text.Encoding]::UTF8.GetBytes("$($creds.username):$($creds.GetNetworkCredential().password)"))

$header = @{Authorization = "Basic $base64Creds"}

And that gives me a working authentication header for NSX-T's API!  Of course, that doesn't do a lot of good by itself... so let's look at one example of using it now.

The NSX-T API Guide is an excellent resource for figuring out what API calls you'll need to make in order to do whatever it is that you want to do.  For example, if I want to get a list of all of the Tier-1 devices, it tells me that I need to use /policy/api/v1/infra/tier-1s/.  So, I put that into my web request like this:

invoke-webrequest -uri "$url/policy/api/v1/infra/tier-1s" -headers $header

And that'll give me back a response... that doesn't quite look like what I'm expecting.  That's because it's an entire web response in JSON formatting (after all, the API doesn't know that we're using PowerShell here and so isn't going to give us a nice PowerShell object).  Fortunately, we can really easily get a PowerShell object out of that web response by converting it from JSON and grabbing the contents of the .results property:

$T1Gateways = (invoke-webrequest -uri "$uri/policy/api/v1/infra/tier-1s" -headers $header | convertfrom-json).results

That'll give me all of the T1 Gateways in my environment!  That's a required first step for many operations, such as creating Network Segments (which need to hang off of a Tier 1 Gateway).  My hope is to put together a whole series of NSX-T API scripting posts, so we'll go into more details on that later!