Getting Started with APIs
In the next sections, we will show you how to create and use API keys with Postman and curl. We'll also show you how any authenticated user can execute the API in a web browser.

Creating an API key

The first step in utilizing the BastionZero API is generating an API key. This key is used to authenticate your API call to the service for your organization. The API key name is used in the BastionZero audit logs so we recommend choosing a key that clearly identifies an intent. In this case, we've chosen a key name that indicates it is used for this KBA demonstration.
PSA: Please remember that API keys are credentials. You should always protect your API keys by restricting access, deleting keys no longer in use, creating keys for different integrations, and using the BastionZero logging service to monitor your API use for inconsistencies and anomalies. Never embed your API keys directly in apps or secret files. Always use a key vault!
Without further comment let's move onto configuration. The first step is to generate the API key. You'll need to give it a unique name and use the copy feature to save away your client ID and client secret before closing the modal.
Go to Create -> API Key
Note, we're leaving the client id and secret here for demonstration purposes. Trust us, they won't work if you try them!
An image showing the API key and secret on the BastionZero web app
Once you provided the API key name, you will see the modal above. Again, remember to capture your API keys which can be done using the copy icon to the right of your keys. You may list all the API keys generated on your platform by going to: Manage API Keys.
An image showing all the keys in a single organization on the BastionZero web app
This completes creating and naming an API key that can be used to make API calls.


Postman Configuration

Postman is an easy to use API tool that facilitates testing the configuration and set up of the BastionZero API. If you haven't already done so, please review the Postman documentation and install the tool from the following URL, installing Postman.

Create Global Variables

The first thing to do is to set up your client secret as a global environment variable. This makes it easy to reuse in your API calls as you set them up in your Postman collection. This is accomplished by selecting the 'Eye' in the upper right of the Postman UI, then 'Edit' in the Globals section of the modal landing you in the variable edit modal. Next, add a new variable and paste your secrets into the initial value column. Below we used 'client_secret' as our variable. We will use this in our Postman setup.
Image showing how to set a global variable in Postman

Test Against the BastionZero API

We will next create an API request to list all targets. Always remember to check BastionZero API for the latest versions. In this example we are using our V1 API.
On Postman, click the '+' icon in the same row as the 'Eye' icon. Postman will open an 'untitled request' to which we will insert the appropriate information:
Image showing a blank request in Postman
Visit Search for 'ssm/list' and notice it is a POST command. The body of the request list some optional schema, which in this case includes dynamic targets. If you didn't wish to include dynamic targets you could include this scheme and change the value to false.
The steps to defining the API are as follows:
  1. 1.
    Change the HTTP method GET to a POST in the drop down.
  2. 3.
    Select the Headers tab.
    1. 1.
      Add 'X-API-KEY' as your header key with the value being your client secret variable. Below mine is {{client_secret}}.
    2. 2.
      Add 'content-type' as another key with the value being 'application/json'.
  3. 4.
    Switch to the Body tab.
    1. 1.
      Select 'Raw' in the drop down box with JSON as being the format (if it does not default).
    2. 2.
      On line 1 add '{ }' for the body of the request.
Your Postman should look very similar to the screen shots below when completed:
Image of what the header of a Postman request looks like when calling the BastionZero API to list all targets
Image of what the body of a Postman request looks like when calling the BastionZero API to list all targets
Don't forgot to name your API and save it in a collection! Once you've verified the above go ahead and hit send. You should receive a JSON list of all your targets, similar to below:
Image of what the response of a Postman request looks like when calling the BastionZero API to list all targets
If your API call failed check the following:
  1. 1.
    Make sure your API secret is valid by associating the API key name with your API key list.
  2. 2.
    Re-check your Postman configuration. Typical errors include forgetting the API body or making sure the auth tab has 'no auth' set in the configuration type.


Curl is a command line tool used for transferring data. It supports many protocols and is commonly used for testing endpoints and running verbose, which is especially helpful when debugging. Using curl with BastionZero requires a user include the content-type and client secret along with the API endpoint and parameters as command arguments. Below is an example of using curl with BastionZero to list all the targets associated with an organization:
Image showing an example of using curl with BastionZero to list all the targets associated with an organization
Notice the insertion of the headers including X-Api-key (client secret) and content-type (application/json).

Web Browser

An authenticated user can also execute APIs directly using their web browser by using the browser's omnibox (or Omnibar). The example below is used to list all API keys associated with my organization.
Image showing an example of using the web browser omnibox to list all API keys associated with the author's organization
Last modified 19d ago