Intro to the Halo API

The Halo portal provides a web-based graphical interface with access to everything you need to secure your cloud servers. The Halo Portal is great for people managing servers, but doesn’t lend itself to programs make changes. To automate management, you need to use an Application Programming Interface (API). In this post I’ll talk about how you can automate management by leveraging the Halo API.

** NOTE ** Halo API has changed since this blog post was written – please see Halo API Developer Guide and Using the Halo API for details

The Halo API provides a powerful set of capabilities enabling you to extend Halo’s functionality through customization and integration with third-party technologies.  It’s a way for automation technologies to make queries about your cloud servers and to make changes to server security settings. The Halo API is available to both Halo NetSec and Halo Pro customers.

Halo API – The Basics

Halo API calls all have the same basic structure:

– They are all HTTPS requests, so we’ll use the curl command line http client to demonstrate.  If curl is not installed, you can install it with the command “sudo apt-get install curl” (on Ubuntu and Debian) or “sudo yum -y install curl” (on Red Hat, CentOS or Fedora).

– The URL called looks like “GET”.  Depending on what you’re trying to do, the “GET” portion of the URL may end up being GET, PUT, POST, or DELETE.

– The API call needs two additional headers; “x-cpauth-access:” and “Content-Type:”.  We’ll see how to add these with curl in a minute.

– If you’re making a change via the API, you’ll have to provide a json-formatted block of data; if you’re only asking the API for information, you don’t have to provide any data.

– Both change requests and information requests return json-formatted output.

– Finally, the “/1/” portion of the above mentioned URL is the API version number.  With a versioned API, the API can be updated without immediately impacting the users of the current version. To make a request to a versioned API, the client needs to prefix the request with /api/{api_version}/. Currently only one version is supported, version 1.

Making a live request from the command line

Let’s pull a list of all the firewall zones (lists of IP addresses with the same security settings) from the API.  This is a simple call, in that we don’t need to provide any information; we’re just pulling down a list of zones.
First, we need an API key – the equivalent of a password that gives you the right to query and make changes – from the portal.  Logon to your Halo account and go to Settings -> Site Administration and click on the “API Keys” tab.  The 32 character hex string to the right of “API Key:”  is what you’ll use in just a moment to get access (See figure 1). Keep it private like any other password.

In the following example, you’ll need to replace {YourAPIKey} with your specific API key value:

curl -sL -H "x-cpauth-access: {YourAPIKey}" -H "Content-Type: application/json" -X GET


If all works, the command will spit out something like:


The 32 character ID’s you’ll see will be different.

In future posts we’ll cover how to make changes via the API and talk about more general requirements for accessing the API from any language.  Until then, feel free to try the different API requests (the ones that use “GET”) found at: .   For example, to get a list of servers:

curl -sL -H "x-cpauth-access: {YourAPIKey}" -H "Content-Type: application/json" -X GET

Stay up to date

Get the latest news and tips on protecting critical business assets.

Related Posts