API key accounts

API key accounts are designed to enable external scripts or integrations to authenticate to the IBM Security Orchestration & Automation application through the REST API, with the minimum required permissions. A system-generated token is used to authenticate. API key accounts cannot access the Orchestration & Automation user interface, own incidents or be members of an incident or group. The API key display name is unique for each platform account in the Orchestration & Automation application.

About this task

Apps installed from the Apps tab automatically create their own API key account. If you have apps deployed using an Integration Server, you must manually create an API key account with a set of permissions required for that app to run successfully.

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

Each API key account contains a server-generated ID and secret and a unique display name, as well as 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 optionally, a description.

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

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


  1. Navigate to the Administrator Settings > Users tab 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. This must be unique in the organization. This is the name for the key that is shown on the Administrator Settings > Users > API Keys tab. Optionally, you can enter a description. From the Permissions section, assign the required permissions for the API key that you are creating.
    The surrounding text describes this graphic, which is a snap shot of the user interface.
  4. Click Create. The API key credentials are displayed.
    The surrounding text describes this graphic, which is a snap shot of the user interface.
  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.


The API key account is created.

To subsequently change the permissions, display name or description, navigate to Administrator Settings > Users > API Keys, select the key that you want to edit, and click Edit. From the editor, change the permissions or display name, as required.

If you need to regenerate the key, click Regenerate API Key Secret. The ID remains the same but a new secret is generated. Any integrations that are using the key account must be updated to match the regenerated key. To delete the key, click Regenerate API Key Secret > Delete API Key.
Important: An API key account is generated automatically whenever an app is installed from the Apps tab. Changing the permissions or regenerating the secret of this API key account could cause the app to stop working.