Axonius REST API

Prev Next

Use the Axonius REST API to perform tasks within the Axonius platform instead of using the User Interface.

Key Features of API v2:

  • Streamlined Endpoints - The initial release includes around 40 endpoints, each focused on the most vital parameters needed to achieve your goals. More endpoints will be added over time.
  • Standardized and Developer-Friendly - The new API adheres to industry standards, making it easier to use and developer-friendly, which in turn speeds up development for Axonius developers.
  • Comprehensive Documentation - Our detailed and cohesive documentation helps users quickly understand which endpoints to use and how to write the necessary code to achieve their objectives.
  • Clear Error Messages - Clear and simple error messages, making it easier to understand and resolve issues.

Access API v2

To start using the API v2, open a Zendesk ticket and select the API v2 option to request access to the documentation.

API v2 Access for Axonius Federal Users

Open a ticket via the Federal Support Portal or email your request to Support@AxoniusFed.com with the subject "Access to APIv2 documentation".

Federal Customers should not open a support request at https://support.axonius.com.

Enabling API Access

Accounts used to access the API must have a role with the API Access enabled permission enabled. This role must also have permissions to perform all actions that will be executed using the API.

To enable API access:

  1. At he top right corner of the page, click image.png. The System Settings page opens.

  2. Click User and Role Management and then Roles.

    image.png

  3. Select the relevant role as described in Manage Roles. For the selected role, under the API Access category, select the API access enabled checkbox.
    image.png

  4. Click Save.

Accessing the API

The following sections explain how to get the API key and API secret for existing customers who started using Axonius with v6.1.73 or earlier and for new customers just starting to use Axonius from v6.1.74 and up.

For Existing Customers of Axonius v6.1.73 and Earlier
If you started using Axonius with v6.1.73 or earlier, the API can be accessed with either an individual user account or a service account. You can also remove API access from individual user accounts and allow it to be accessible only by service accounts. This enhances the security of your environment.

To use the API you must use the API key and API secret of the account used to access the API. This applies to both individual user accounts and service accounts.

For new Axonius Customers from v6.1.74 and Up
If you started using Axonius with v6.1.74 or later, the API can be only accessed with a service account. The API secret is only visible when the account is created or when the API key is reset.

Note:

Whether you access the API with an individual account or a service account, the account you use must have a role that has been granted the permissions to perform all the actions that the API will be used for. You can use different service accounts with different roles to restrict what actions can be done with the API by any specific service account.

Getting the API Key and API Secret for Individual Accounts

The API key and API secret must be entered into the header parameters of every API call.

Note:

The API secret, once displayed in the original message when it is created, is not retrievable. If the API secret is lost, you must reset the API key to generate a new key and secret.

To get the API Key and API Secret for an individual account:

  1. Log in to Axonius with a user account whose role has the API access enabled permission.

  2. At the top-right of the page, click on your account avatar.
    UserAvatarUserSettings.png

  3. Click User Settings and then click the API Key tab.

  4. Click Reset Key. You should reset the key if you forgot or lost the secret. Rotating the key is also recommended as part of a robust security policy.
    IndivAccountAPIKey.png

  5. A message box is displayed. Resetting the API key means that any API-based applications running with this API key will no longer have access to the API. You will need to update these applications to use the new key. Click Reset Key to reset the key.
    APIResetKeyWarningModal.png

  6. A message box displays the API Key and API Secret that allow the account to access the API.

    Important:

    ServiceAccountKey1

    The API secret is only displayed in this message and not anywhere else in Axonius. You must copy it to a safe location as it cannot be recovered. Click ServiceAccountCopyIcon.png to copy the API secret and save it in a safe place, or manage it using a password management system.

Removing API Access from Individual User Accounts

Existing customers who started using Axonius with v6.1.73 or earlier can enhance the security of your environment by removing API access from individual user accounts and restricting access to service accounts only.

To remove API access from individual user accounts:

  1. From the top right corner the page, click image.png. The System Settings page opens.

  2. Go to User and Role Management and then Service Accounts.

  3. Select Disable API Key Usage for Users.
    DisableUserAPIKeys.png

  4. A message box is displayed explaining that disabling API access to individual user accounts cannot be reversed. All API access by regular user accounts will be blocked and their API keys and secrets revoked. This action is permanent and irreversible.
    APIRevokeMessage.png

  5. To confirm and disable API access to individual user accounts, click Yes, disable API access for users. Access to the API for individual accounts is permanently disabled and Disable API Key Usage for Users option is also disabled and no longer available.

Getting the API Key and Secret for Service Accounts

The API Key and API Secret must be entered into the header parameters of every API call. See Managing Service Accounts for more about Service Accounts.

To get the API Key and API Secret for a service account:

  1. From the top right corner the page, click image.png. The System Settings page opens.

  2. Go to User and Role Management and then Service Accounts.

  3. Select a service account.

  4. Scroll down and expand Optional details.

  5. The API Key is displayed in the API Key field.

  6. To reset the API Key and also get the API Secret, click ResetCircles.png (Reset).

  7. A message box displays the API Key and API Secret that allow the account to access the API.

    Important:

    ServiceAccountKey1

    The API Secret for the account is not saved anywhere on the Axonius system. You must copy it to a safe location as it is not kept and cannot be recovered. Click ServiceAccountCopyIcon.png to copy the API secret and save it in a safe place, or manage it using a password management system.

The REST API Headers

When sending an API request using the REST API with Postman, curl, or any other tool, the API key and API secret and other information must be provided as Headers. In Postman, you enter these values in the Headers tab.

To enter the API Key and API Secret into Postman headers:

  1. On the Headers tab, click in the Key field of the last row and enter the text api-key. As soon as you enter a value in this row, a new empty row is added below the current row.
  2. In the Value field enter the API Key obtained using the instructions above.
  3. In the next row, in the Key field enter api-secret.
  4. In the Value field enter the API Secret obtained using the instructions above.

You also must define the content type.

To specify the content type:

  1. On the Headers tab, in the empty Key and Value fields under api-secret, enter the following:
    • In the Key field enter Content-Type.
    • In the Value field enter application/vnd.api+json.

REST-API-Headers.png