If you’ve never used an API before and want Automox to be your first (you always remember your first API) then this is the guide for you. By the end of this document you’ll have made your first API call and can see the results from your environment.
Step 1: Download Postman
Postman is a handy tool for testing out API calls to make sure they work before putting them in a script. They have a freemium version for individuals and small teams that you can download:
They’ve got versions for Windows, Mac and Linux so it doesn’t matter what OS you are working on.
Install Postman and create yourself a login and you’re ready for the next step.
Step 2: Find your API key in the console
In your Automox console, click on Settings and then API:
You’ll want the API key (the one on the bottom). There’s a handy copy icon to the right of the API key to get it into your clipboard.
Step 3: Create your first API call
For this exercise, we’re going to use the “Retrieve details for all policies” API call. The documentation for that call is found here:
Dev Portal - Automox API Guide
List All Policy Objects
Retrieves a list of all policy objects for the authenticated user.
Open up Postman and click on New button in the upper left, then Request. From there, paste the following command into the Get window:
Grab the API key from Step 2, click on the Authorization tab, and select type Bearer Token in the dropdown. Then paste your API key in the Token field:
If you only have one Automox organization then you can click on Send. If not, you’ll need to add a parameter to specify which organization you want to pull the policies from. To get the Organization ID (or OrgID) for the organization, go into your console and switch to the organization you want:
Then the OrgID will be the last part of your console URL in the browser:
The 0000 is the number we want from the URL (in your case it will be a different number).
Once you have the OrgID, go back to the Params tab in Postman. In the Key field, put the letter o. In the Value field, put the OrgID. You’ll note that the Get field will update to include ?o=0000 at the end of the API call.
Click Send and then you should see a bunch of code appear in the Body section below the Query Params:
If you get any sort of error code, double-check to make sure you copied your OrgID and API Key correctly. If they don’t match up then the API won’t return any data because it doesn’t recognize you as authorized to do so:
Step 4: Pat yourself on the back
Congratulations, you’ve made your first API call!
Scrolling through the returned JSON will show you each of your policies, with all their associated data, in a tree structure.
Step 5: What now?
Now that you’re no longer an API newbie, you can put your API call into a script and start working with your data. Each of the API calls has example code in various languages at the bottom of the API documentation page:
Once you’ve extracted the data you need via the API, you can crunch it for handy reporting. You can either use a tool built for that purpose, such as one of these.
Best Business Intelligence (BI) tools
Got questions? Stuck? Reply below to ask for help!
Note: don’t include your API key in anything you post to the community. That’s your secret key that you want to keep to yourself to protect access to your data.
This is a nice guide, but could we update it to reflect recent changes?
Good call - I need to update that to include the new API limits and anything else that’s changed. I’ll add that to my todo list!
Hi Guys. I’m trying to create a new policy via the API using “policy_type_name”: “custom”.
The docs don’t say what parameters to use for the Evaluation and Remediation code.
Looks like we didn’t put those field names in the documentation, sorry about that. Under the configuration object there are two properties for:
You will have to escape any special characters using the backslash, for the code that you insert into those properties. If you do a GET on an existing worklet it will show you the syntax if you’re having issues getting the code blocks properly formatted for the API call.
Ah, thank you, Nic. It’s working!
Glad that worked!
lets say I wanted to do a put to update a device’s custom name field. what parameters are required in postman? getting 405 “method not allowed” with the following set (auth tab configured w/ API key as described in guide):
Hi. I’m no Postman expert, but I did this and it worked…
First I created an environment for my test org (5002) with my API key and the API URL:
Then I modified the Params for the PUT setting o=5002, the server_group_id, and the custom_name I wanted to set that device to. If you’re not sure of the server_group_id, go to the group page for the group that the device is in and pull the number next to “gid=” in the URL.
Then I went to the Auth tab and set the variable from my 5002 environment in double squiggly brackets