At Action1, we are all about automation, making life easier for admins and patching compliance teams everywhere. That is why we provide a robust API that lets you capitalize on the flexibility and ease of use of Action1 while having an ever-expansive toolset to take your needs to the next level.
A significant part of the success of Action1 has been its simplicity of use: no weeks researching and testing features, just sign up and go. So naturally we wanted the API experience to be as simple and accessible as the rest of the system. API use can often be complex and therefore come off as exceedingly difficult to get started in, but it does not have to be hard at all.
With PSAction1, you have access to many of the API features in the convenience of simple, logical PowerShell commands. Working with objects in much the same manner that you do other PowerShell commands, using familiar logic and syntax. In this multi-part series, we will go over getting started, some practical use cases, and more advanced use cases to highlight the utility PSAction1 can bring to your Action1 system.
To get started, let’s first talk about some PowerShell basics as they relate to module use. This is, in general, just how PowerShell works, not specifically how PSAction1 works. If you fully understand modules in PowerShell, feel free to skip ahead… The module is publicly available through our Git repo if you plan to run the current bleeding-edge build. This is where you would find bug fixes in progress, possibly new features being tested, etc.
However, most will likely want to pull the stable release version directly from Microsoft’s PowerShell Gallery. Installation is simple, but this step does require an elevated PowerShell instance, as installing PowerShell modules is considered an administrative function.
How to Install PSAction1?
Step 1. Open a PowerShell instance as an administrator. Elevation is needed to install PowerShell modules.
Step 2. Run the following command to install the PSAction1 module:
You will be prompted to confirm this operation and warned that the Microsoft repository is non-trusted. If uncertain what this warning means, consult your systems administrator.
Step 3. Then execute this command:
This will confirm the installation was successful and can be used again in the future to see what version you have installed. If any issues are encountered, troubleshooting should always start with making sure you have the latest module that has been published.
On success, the entire process should appear as below:
So, with that out of the way, PSAction1 should now be installed and ready to go; let’s get started. The first thing to remember is that as an API, this is an interface to the secure system— so nothing can happen without authentication.
How to Create and Configure API Credentials in Action1?
Step 1. Head over to your Action1 instance, log in, and navigate to the configuration section on the left panel and select “API Credentials” then “+New.”.
Step 2. Give your API key a meaningful name, select the organization you want to have access to, or select the whole enterprise.
Step 3. On the next screen, you will be given an API key and a system-generated secret. Make sure to document them, as you will not be able to see them once you close this window. If you lose the secret, you will have to delete and recreate the API key as it cannot be recovered.
And that’s it; with the module installed, the API key, and the secret, we are ready to get something done for real.
Authenticating in PSAction1
To set up a session, you must select the region your host is in, authenticate, and set the context of at least one organization. These are the only steps out of everything above that will be needed each time you use the module before starting any other operations. For your convenience, we have created a detailed step-by-step guide to follow:
Step 1. Tell PSAction1 which region you log into, corresponding to the region you select on your Action1 login page, with the following command:
You can see valid options for other regions by tabbing through the list.
Step 2. You must pass the API key and secret; this parameter is effectively the API username & password.
Step 3. Now, you must set a context for the first org your API key has access to by executing the following command:
Keep in mind that if you are an organization admin, it will be the org assigned to that API key; if you are an enterprise admin, it can be any valid org in your enterprise. The org ID can be seen in the URL of any Action1 page as “org=a6cead30-9592-4ff1-8375-4a4a39a22cbe”; your org ID will be different than this example.
When you log onto Action1’s API, you are given a token that represents your session. PSAction1 manages that token and checks for validity prior to any API request. If the token has expired between operations, it will automatically renew it on your behalf.
Now, let’s put all of that to work! Let’s run a simple query to make sure everything is in working order.
Your First Query Using PSAction1:
Now that everything is ready, use PSAction1 to run your first query. Just follow these steps:
Step 1. Run the following command:
If you did everything correctly to this point, a bunch of information should have just scrolled by.
In case you still do not see anything, use the following command:
Its default state is “true,” but I listed it to demonstrate it can be turned off and on. This is an assistive mode that, for instance, if you forgot to provide an org, an API key, or a secret… PSAction1 will prompt you for the missing element to make its initial config work. If you disable this mode (which should be the case for non-interactive scripts), it will report the missing elements instead of prompting you for them.
Step 2. Now let’s format our output for better readability by executing this command:
This time a window should pop up that cleanly lays out each column and row into a searchable/sortable format much like a spreadsheet, as seen below.
Step 3. Neat, but still a lot of information to process through. So let‘s get more specific and simplify the output:
And now we have something much more useful!
Using this syntax should be familiar to any PowerShell user, and in a simple one-liner, we have done something particularly useful with the API for Action1, using PSAction1.
Using this simple stacked set of progressive functions, this can easily be expanded to find specifics on a more granular scale, such as “locate all systems that match a specific pattern,” such as accounting systems or engineering systems, possibly customer naming convention patterns…
Step 4. In the following example, I filter endpoints to only those that start with “A1-Sheep- and then two digits.”
Step 5. If you need to exchange that information with someone else, making a CSV that will open in Excel is just as easy; just modify the above command slightly:
So on and so forth. With just a little PowerShell knowledge and a basic understanding of how PSAction1 operates, you are already taking your API skills and your Action1 skills to the next level! Without all the brain-melting complexity you may have always thought it would be!
Remember that the Get-Action1 cmdlet is harmless at this point; you cannot harm a system by experimenting with it.
It is simply asking the system for information and modeling it in PowerShell memory locally. So, I suggest working with it a little at this level to make sure you know how data comes out of the system and can be refined orprocessed into smaller, more useful sets. That ability will be assumed in part 2.
In future examples we will get into the usage of things like New-Action1 and Update-Action1 where things in the server instance can be modified.
In part 2, “Getting the most out of Action1 with PSAction1,” will go over some more advanced use cases to see what some of the more advanced features of PSAction1 can do to assist you in getting the most out of your Action1 system. We will cover how to create, modify, and Delete items in Action1.
