API key accounts

API key accounts are designed to enable external scripts or apps to authenticate to the SOAR Platform through the REST API, with the minimum permissions. A system-generated token is used to authenticate. API key accounts are not linked to LDAP and cannot access the SOAR Platform user interface, own incidents or be members of an incident or group. The API key display name is unique for each organization in the SOAR Platform.

About this task

Apps that are installed using the Apps tab automatically create their own API key account. For apps that are deployed with the Integration Server, manually create an API key account with a set of permissions that are needed for that app to run successfully.

When you create an API key account, you must specify a display name for the account. You can also assign the minimum permissions that are needed for that key account. For example, if the script or app that accesses the SOAR Platform requires only permission to edit incidents, you can assign only these permissions.
Note: To create and manage API key accounts, your global role must have the API Keys permission, which is assigned from the Administration and Customization Permissions. If you upgraded from a previous version of the SOAR Platform, you must assign this permission to one or more roles.

Each API key account contains a server-generated ID and secret, a unique display name, and the permissions assigned. It also contains the user who created or last updated the key account and the created or updated time and date, and if added, a description.

API key accounts ignore two factor authentication. In addition, API key accounts cannot access the SOAR Platform user interface. They cannot own or be members of incidents, own or be members of tasks, or be members of a group.

Incidents that are created by API key accounts are automatically assigned to the default group if an incident owner is not specified during incident creation.

Procedure

  1. Go to Administrator Settings > Users and click the API Keys tab.
  2. Click Create API Key.
  3. From the Create API Key screen, enter the display name for the API key account. It must be unique in the organization. The display name is shown on the Administrator Settings > Users > API Keys tab. You can also enter a description. From the Permissions section, assign the necessary permissions for the API key that you are creating.
  4. Click Create. The API key credentials are displayed.
  5. Make a note of the credentials and store them safely as you cannot retrieve them after you click OK. Then click OK to proceed.

Results

The API Key Account is created.

To change the permissions, display name, or description, go to Administrator Settings > Users > API Keys, select the key to edit, and click Edit. From the editor, change the permissions or display name, as needed.

If you need to regenerate the key, see Regenerating an API key.

To delete the key, click Regenerate API Key Secret > Delete API Key.

By default, the API Key account expires in one year. For on-premises installations, you can modify the expiration date as described in Password and API key expiration.

Important: An API key account is generated automatically whenever an app is installed using the Apps tab. Changing the permissions or regenerating the secret of this account might cause the app to stop working.