Configure API management alerts

Configure API Manager to generate alerts when specific events occur.

18 minute read

API Manager can generate alerts when specific events occur. For example, it can generate an alert when an organization is created or deleted, or when access is granted to an API. When an alert is generated by API Manager you can execute a custom policy to handle the alert. Sample policies are provided as a starting point for custom development.

You can enable or disable alerts in the API Manager web interface. You can change the policy that is executed when an alert is generated in Policy Studio.

You can use alerts for many different use cases. For example, to send an e-mail to an interested party, or to forward the alert to an external notification system. The following video shows how you can integrate with JIRA, for example, to generate issues there. You can then set up the necessary workflows in JIRA for your use case.

Alert descriptions

Alerts are categorized according to the type of event that generates the alert, for example, organization events are in a different category to application events. The following sections list the alerts in each category, and detail the event that triggers the alert, and the type of the alert (governance or runtime). Events initiated by a person (for example, an administrator approves an API consumer registration) are governance alerts. Events that occur during normal operation of the system are runtime alerts.

Application alerts and events

API Manager generates application alerts for events relating to managing applications.

Alert Name Alert Type Trigger Event
Approve Application Registration Governance When a new application has been registered but approval is needed (auto-approve disabled).
Application Approved Governance When a new application registration is approved (including auto-approve).
Delete Application Governance When an application is deleted. Except when the organization is deleted - do not generate an alert for each application in the organization.
Enable Application Governance When an application is enabled.
Disable Application Governance When an application is disabled.
Approve Application API Access Request Governance When an application is requesting access to an API but approval is needed (auto-approve disabled).
Application API Access Approved Governance When an application request to access an API is approved (including auto-approve).
Remove Application API Access Governance When authorization to access an API is removed from an application.
Enable Application API Access Governance When an application’s API access is enabled.
Disable Application API Access Governance When an application’s API access is disabled.

Application credential alerts and events

You can use application credential alerts when you want to trigger alerts for any change to the credentials (API keys, OAuth credentials, or external credentials) associated with an application. Application credential alerts are fully configurable:

  • Policy developers can write policies that will be invoked when application credentials are created, updated, deleted, enabled, or disabled. For more information, see Change the alert policy to execute. For more information on the message attributes available to application credential alert policies, see Alert message attributes.
  • API administrators can enable or disable alerts for application credentials so that the configured policies get executed when the specified events are triggered. For more information, see Enable or disable alerts.

API Manager generates application credential alerts for events relating to application credentials.

Alert Name Alert Type Trigger Event
Create Application Credential Governance When an application credential is created.
Delete Application Credential Governance When an application credential is deleted.
Enable Application Credential Governance When an application credential is enabled.
Disable Application Credential Governance When an application credential is disabled.
Update Application Credential Governance When an application credential is updated.

When an application credential alert is triggered, the following users are notified:

  • The application developer that created the application associated with the credential being created, modified, or deleted.
  • Any application developer that has manage permissions for the application associated with the credential being created, modified, or deleted.

API registration alerts and events

API Manager generates API registration alerts for events relating to managing APIs.

Alert Name Alert Type Trigger Event
API Proxy Published Governance API owner publishes API proxy. Also triggered when an organization administrator requests to publish (the policy attribute alert.apiproxy.state is then pending).
API Proxy Unpublished Governance API owner unpublishes API proxy.
API Proxy Deprecated Governance When an API proxy is deprecated.
API Proxy Retired Governance When an API proxy is retired (unpublished).
API Proxy Promoted Governance API owner promotes API proxy using the configured API promotion policy.

API catalog alerts and events

API Manager generates API catalog alerts for events relating to enabling and disabling APIs.

Alert Name Alert Type Trigger Event
Enable API Governance When an API is enabled in the API catalog.
Disable API Governance When an API is disabled in the API catalog.

Application developer alerts and events

API Manager generates application developer alerts for events relating to managing application developers.

Alert Name Alert Type Trigger Event
Approve Application Developer Registration Governance When a new application developer user is registered but approval is needed (auto-approve disabled).
Application Developer Approved Governance When a new application developer user registration is approved (including auto-approve).
Delete Application Developer Governance When an application developer user is deleted. This alert is not generated for each user when an organization is deleted.
Enable Application Developer Governance When an application developer is enabled.
Disable Application Developer Governance When an application developer is disabled.
Reset Application Developer Password Governance When an application developer password is reset (not changed).

Organization alerts and events

API Manager generates organization alerts for events relating to managing organizations.

Alert Name Alert Type Trigger Event
Create Organization Governance When an organization is created.
Delete Organization Governance When an organization is deleted.
Enable Organization Governance When an organization is enabled.
Disable Organization Governance When an organization is disabled.
Add Organization API Access Governance When authorization to access an API is granted to an organization.
Remove Organization API Access Governance When authorization to access an API is removed from an organization.
Enable Organization API Access Governance When an organization’s API access is enabled.
Disable Organization API Access Governance When an organization’s API access is disabled.

Quota alerts and events

API Manager generates quota alerts for events relating to system or application quotas.

Alert Name Alert Type Trigger Event
System Quota Exceeded Runtime When a system quota is exceeded.
System Quota Warning Exceeded Runtime When a system quota warning threshold is exceeded.
Application Quota Exceeded Runtime When an application quota is exceeded (application default quota or application specific quota).
Application Quota Warning Exceeded Runtime When an application quota warning threshold is exceeded (application default quota or application specific quota).
System Quota Changed Governance When a system quota is changed.
Application Default Quota Changed Governance When an application default quota is changed.
Application Specific Quota Changed Governance When an application specific quota is changed.
Application Specific Quota Deleted Governance When an application specific quota is deleted.

Enable or disable alerts

You can enable or disable alerts in the API Manager web interface. Click the Settings > Alerts view in API Manager. Alerts are disabled by default.

The following figure shows the view of API management alerts in API Manager.

Web-based API management alerts

To enable or disable an alert, click the On/Off button next to the alert. Changes are saved automatically.

Change the alert policy to execute

When an enabled alert is generated, the policy associated with that alert is executed. The alert context provides the policy with a number of message attributes. These are specific to the alert being generated (for example, alert.application, alert.appdev, alert.organization). By default, each alert is configured to execute a sample policy, and the sample policy demonstrates the attributes from the respective alert context. You can change what happens when an alert is generated, either by modifying the sample policy associated with the alert, or by creating a custom policy and associating that policy with the alert.

You can change the policy that is executed when an alert is generated in Policy Studio. To view the API management alerts and the associated policies, click the Server Settings node in the Policy Studio tree view. On the Server Settings tab, expand the API Manager tree node and click Alerts.

The following figure shows the view of API management alerts in Policy Studio.

Policy-based API management alerts

To modify the sample policy associated with an alert, click the sample policy link next to the alert.

To associate a different policy with an alert, click the row containing the alert, and click the Edit button. In the dialog, click the browse button to select a new Alert Policy and then click OK. To save any changes, click the Save button.

Alert message attributes

This topic describes the message attributes that are available to the configured alert policies.

The following tables outline the message properties that are generated for each alert. All message property values are in string format. Message properties are only available if a value exists for the entity field in question.

Application credential alert properties

Message property Description
alert.recipient.emails Comma separated list of email addresses of recipients of alert emails.
alert.appcredential.type Specifies the type of application credential associated with the alert. This message property is present for all application credential alerts. Possible values are: ["apikey", "oauth", "external"].
alert.user.id The identifier of the user (logged into API Manager) that triggered the alert. A subsequent call to the Read Application Developer filter can be used to retrieve the user object.

Application credential created

API Key:

Message property Description
alert.appcredential.apikey.id The identifier of the newly created API key. Format: GUID.
alert.appcredential.apikey.applicationId The identifier of the application associated with the newly created API key. Format: GUID.
alert.appcredential.apikey.secret The secret associated with the newly created API key. Format: GUID.
alert.appcredential.apikey.enabled Specifies whether the newly created API key is enabled or disabled. Possible values are: [ "true", "false" ].
alert.appcredential.apikey.createdBy The identifier of the user that created the API key. Format: GUID.
alert.appcredential.apikey.createdOn The time, in milliseconds, when the API key was created
alert.appcredential.apikey.deletedOn The time, in milliseconds, when the API key was deleted.
alert.appcredential.apikey.corsOrigins Comma-separated list of origins associated with the newly created API key.

OAuth:

Message property Description
alert.appcredential.oauthclient.id The identifier of the newly created OAuth credential. Format: GUID.
alert.appcredential.oauthclient.applicationId The identifier of the application associated with the newly created OAuth credential. Format: GUID.
alert.appcredential.oauthclient.enabled Specifies whether the newly created OAuth credential is enabled or disabled. Possible values are: [ "true", "false" ].
alert.appcredential.oauthclient.cert The PEM-encoded certificate associated with the newly created OAuth credential.
alert.appcredential.oauthclient.secret The secret associated with the newly created OAuth credential. Format: GUID.
alert.appcredential.oauthclient.type The client type of the newly created OAuth credential. Possible values are: [ "public", "confidential" ].
alert.appcredential.oauthclient.createdBy The identifier of the user that created the OAuth credential. Format: GUID.
alert.appcredential.oauthclient.createdOn The time, in milliseconds, when the OAuth credential was created.
alert.appcredential.oauthclient.corsOrigins Comma-separated list of origins associated with the newly created OAuth credential.
alert.appcredential.oauthclient.redirectUrls Comma-separated list of redirect URLs associated with the newly created OAuth credential.

External:

Message property Description
alert.appcredential.externalclient.id The identifier of the newly created external credential. Format: GUID.
alert.appcredential.externalclient.clientId The client identifier associated with the newly created external credential. Format: GUID.
alert.appcredential.externalclient.internalClientId
alert.appcredential.externalclient.applicationId The identifier of the application associated with the newly created external credential. Format: GUID.
alert.appcredential.externalclient.enabled Specifies whether the newly created external credential is enabled or disabled. Possible values are: [ "true", "false" ].
alert.appcredential.externalclient.createdBy The identifier of the user that created the external credential. Format: GUID.
alert.appcredential.externalclient.createdOn The time, in milliseconds, when the external credential was created.
alert.appcredential.externalclient.corsOrigins Comma-separated list of origins associated with the newly created external credential.

Application credential updated

API Key:

Message property Description
alert.appcredential.existing.apikey.id The identifier of the existing API key, before the update. Format: GUID.
alert.appcredential.existing.apikey.applicationId The identifier of the application associated with the existing API key, before the update. Format: GUID.
alert.appcredential.existing.apikey.secret The secret associated with the existing API key, before the update. Format: GUID.
alert.appcredential.existing.apikey.enabled Specifies whether the existing API key was enabled or disabled, before the update. Possible values are: [ "true", "false" ].
alert.appcredential.existing.apikey.createdBy The identifier of the user that created the existing API key, before the update. Format: GUID.
alert.appcredential.existing.apikey.createdOn The time, in milliseconds, when the existing API key was created, before the update .
alert.appcredential.existing.apikey.deletedOn The time, in milliseconds, when the existing API key was deleted, before the update.
alert.appcredential.existing.apikey.corsOrigins Comma-separated list of origins associated with the existing API key, before the update.
alert.appcredential.apikey.id The identifier of the updated API key. Format: GUID.
alert.appcredential.apikey.applicationId The identifier of the application associated with the updated API key. Format: GUID.
alert.appcredential.apikey.secret The secret associated with the updated API key. Format: GUID.
alert.appcredential.apikey.enabled Specifies whether the updated API key is enabled or disabled. Possible values are: [ "true", "false" ].
alert.appcredential.apikey.createdBy The identifier of the user that created the updated API key. Format: GUID.
alert.appcredential.apikey.createdOn The time, in milliseconds, when the updated API key was created.
alert.appcredential.apikey.deletedOn The time, in milliseconds, when the updated API key was deleted.
alert.appcredential.apikey.corsOrigins Comma-separated list of origins associated with the updated API key.

OAuth:

Message property Description
alert.appcredential.oauthclient.id The identifier of the updated OAuth credential. Format: GUID.
alert.appcredential.oauthclient.applicationId The identifier of the application associated with the updated OAuth credential.Format: GUID.
alert.appcredential.oauthclient.enabled Specifies whether the updated OAuth credential is enabled or disabled. Possible values are: [ "true", "false" ].
alert.appcredential.oauthclient.cert The PEM-encoded certificate associated with the updated OAuth credential.
alert.appcredential.oauthclient.secret The secret associated with the updated OAuth credential. Format: GUID.
alert.appcredential.oauthclient.type The client type of the updated OAuth credential. Possible values are: [ "public", "confidential" ].
alert.appcredential.oauthclient.createdBy The identifier of the user that created the updated OAuth credential. Format: GUID.
alert.appcredential.oauthclient.createdOn The time, in milliseconds, when the updated OAuth credential was created.
alert.appcredential.oauthclient.corsOrigins Comma-separated list of origins associated with the updated OAuth credential.
alert.appcredential.oauthclient.redirectUrls Comma-separated list of redirect URLs associated with the updated OAuth credential.
alert.appcredential.existing.oauthclient.id The identifier of the OAuth credential, before the update. Format: GUID.
alert.appcredential.existing.oauthclient.applicationId The identifier of the application associated with the OAuth credential, before the update. Format: GUID.
alert.appcredential.existing.oauthclient.enabled Specifies whether the OAuth credential was enabled or disabled, before the update. Possible values are: [ "true", "false" ].
alert.appcredential.existing.oauthclient.cert The PEM-encoded certificate associated with the OAuth credential, before the update .
alert.appcredential.existing.oauthclient.secret The secret associated with the OAuth credential, before the update. Format: GUID.
alert.appcredential.existing.oauthclient.type The client type of the OAuth credential, before the update. Possible values are: [ "public", "confidential" ].
alert.appcredential.existing.oauthclient.createdBy The identifier of the user that created the OAuth credential, before the update. Format: GUID.
alert.appcredential.existing.oauthclient.createdOn The time, in milliseconds, when the OAuth credential was created, before the update.
alert.appcredential.existing.oauthclient.corsOrigins Comma-separated list of origins associated with the OAuth credential, before the update.
alert.appcredential.existing.oauthclient.redirectUrls Comma-separated list of redirect URLs associated with the OAuth credential, before the update.

External:

Message property Description
alert.appcredential.externalclient.id The identifier of the updated external credential. Format: GUID.
alert.appcredential.externalclient.clientId The client identifier associated with the updated external credential. Format: GUID.
alert.appcredential.externalclient.internalClientId
alert.appcredential.externalclient.applicationId The identifier of the application associated with the updated external credential. Format: GUID.
alert.appcredential.externalclient.enabled Specifies whether the updated external credential is enabled or disabled. Possible values are: [ "true", "false" ].
alert.appcredential.externalclient.createdBy The identifier of the user that created the updated external credential. Format: GUID.
alert.appcredential.externalclient.createdOn The time, in milliseconds, when the updated external credential was created.
alert.appcredential.externalclient.corsOrigins Comma-separated list of origins associated with the updated external credential.
alert.appcredential.existing.externalclient.id The identifier of the external credential, before the update. Format: GUID.
alert.appcredential.existing.externalclient.clientId The client identifier associated with the external credential, before the update. Format: GUID.
alert.appcredential.existing.externalclient.internalClientId
alert.appcredential.existing.externalclient.applicationId The identifier of the application associated with the external credential, before the update. Format: GUID.
alert.appcredential.existing.externalclient.enabled Specifies whether the external credential was enabled or disabled, before the update. Possible values are: [ "true", "false" ].
alert.appcredential.existing.externalclient.createdBy The identifier of the user that created the external credential, before the update. Format: GUID.
alert.appcredential.existing.externalclient.createdOn The time, in milliseconds, when the external credential was created, before the update.
alert.appcredential.existing.externalclient.corsOrigins Comma-separated list of origins associated with the external credential, before the update.

Application credential deleted

API Key:

Message property Description
alert.appcredential.apikey.id The identifier of the deleted API key. Format: GUID.
alert.appcredential.apikey.applicationId The identifier of the application associated with the deleted API key. Format: GUID.
alert.appcredential.apikey.secret The secret associated with the deleted API key. Format: GUID.
alert.appcredential.apikey.enabled Specifies whether the deleted API key was enabled or disabled. Possible values are:[ "true", "false" ].
alert.appcredential.apikey.createdBy The identifier of the user that created the deleted API key. Format: GUID.
alert.appcredential.apikey.createdOn The time, in milliseconds, when the deleted API key was created
alert.appcredential.apikey.deletedOn The time, in milliseconds, when the API key was deleted.
alert.appcredential.apikey.corsOrigins Comma-separated list of origins associated with the deleted API key.

OAuth:

Message property Description
alert.appcredential.oauthclient.id The identifier of the deleted OAuth credential. Format: GUID.
alert.appcredential.oauthclient.applicationId The identifier of the application associated with the deleted OAuth credential. Format: GUID.
alert.appcredential.oauthclient.enabled Specifies whether the deleted OAuth credential was enabled or disabled. Possible values are: [ "true", "false" ].
alert.appcredential.oauthclient.cert The PEM-encoded certificate associated with the deleted OAuth credential.
alert.appcredential.oauthclient.secret The secret associated with the deleted OAuth credential. Format: GUID.
alert.appcredential.oauthclient.type The client type of the deleted OAuth credential. Possible values are: [ "public", "confidential" ].
alert.appcredential.oauthclient.createdBy The identifier of the user that created the deleted OAuth credential. Format: GUID.
alert.appcredential.oauthclient.createdOn The time, in milliseconds, when the OAuth credential was created.
alert.appcredential.oauthclient.corsOrigins Comma-separated list of origins associated with the deleted OAuth credential.
alert.appcredential.oauthclient.redirectUrls Comma-separated list of redirect URLs associated with the deleted OAuth credential.

External:

Message property Description
alert.appcredential.externalclient.id The client identifier associated with the deleted external credential. Format: GUID.
alert.appcredential.externalclient.clientId The client identifier associated with the deleted external credential. Format: GUID.
alert.appcredential.externalclient.internalClientId
alert.appcredential.externalclient.applicationId The identifier of the application associated with the deleted external credential. Format: GUID.
alert.appcredential.externalclient.enabled Specifies whether the deleted external credential was enabled or disabled. Possible values are: [ "true", "false" ].
alert.appcredential.externalclient.createdBy The identifier of the user that created the deleted external credential. Format: GUID.
alert.appcredential.externalclient.createdOn The time, in milliseconds, when the deleted external credential was created.
alert.appcredential.externalclient.corsOrigins Comma-separated list of origins associated with the deleted external credential.

Application credential enabled

API Key:

Message property Description
alert.appcredential.apikey.id The identifier of the enabled API key. Format: GUID.
alert.appcredential.apikey.applicationId The identifier of the application associated with the enabled API key. Format: GUID.
alert.appcredential.apikey.secret The secret associated with the enabled API key. Format: GUID.
alert.appcredential.apikey.enabled Specifies whether the enabled API key was enabled or disabled. Possible values are:[ "true", "false" ].
alert.appcredential.apikey.createdBy The identifier of the user that created the enabled API key. Format: GUID.
alert.appcredential.apikey.createdOn The time, in milliseconds, when the enabled API key was created .
alert.appcredential.apikey.deletedOn The time, in milliseconds, when the enabled API key was deleted.
alert.appcredential.apikey.corsOrigins Comma-separated list of origins associated with the enabled API key.

OAuth:

Message property Description
alert.appcredential.oauthclient.id The identifier of the enabled OAuth credential. Format: GUID.
alert.appcredential.oauthclient.applicationId The identifier of the application associated with the enabled OAuth credential. Format: GUID.
alert.appcredential.oauthclient.enabled Specifies whether the enabled OAuth credential was enabled or disabled. Possible values are: [ "true", "false" ].
alert.appcredential.oauthclient.cert The PEM-encoded certificate associated with the enabled OAuth credential.
alert.appcredential.oauthclient.secret The secret associated with the enabled OAuth credential. Format: GUID.
alert.appcredential.oauthclient.type The client type of the enabled OAuth credential. Possible values are: [ "public", "confidential" ].
alert.appcredential.oauthclient.createdBy The identifier of the user that created the enabled OAuth credential. Format: GUID.
alert.appcredential.oauthclient.createdOn The time, in milliseconds, when the enabled OAuth credential was created.
alert.appcredential.oauthclient.corsOrigins Comma-separated list of origins associated with the enabled OAuth credential.
alert.appcredential.oauthclient.redirectUrls Comma-separated list of redirect URLs associated with the enabled OAuth credential.

External:

Message property Description
alert.appcredential.externalclient.id The identifier of the enabled external credential. Format: GUID.
alert.appcredential.externalclient.clientId The client identifier associated with the enabled external credential. Format: GUID.
alert.appcredential.externalclient.internalClientId
alert.appcredential.externalclient.applicationId The identifier of the application associated with the enabled external credential. Format: GUID.
alert.appcredential.externalclient.enabled Specifies whether the enabled external credential was enabled or disabled. Possible values are: [ "true", "false" ].
alert.appcredential.externalclient.createdBy The identifier of the user that created the enabled external credential. Format: GUID.
alert.appcredential.externalclient.createdOn The time, in milliseconds, when the enabled external credential was created.
alert.appcredential.externalclient.corsOrigins Comma-separated list of origins associated with the enabled external credential.

Application credential disabled

API Key:

Message property Description
alert.appcredential.apikey.id The identifier of the disabled API key. Format: GUID.
alert.appcredential.apikey.applicationId The identifier of the application associated with the disabled API key. Format: GUID.
alert.appcredential.apikey.secret The secret associated with the disabled API key. Format: GUID.
alert.appcredential.apikey.enabled Specifies whether the disabled API key was enabled or disabled. Possible values are:[ "true", "false" ].
alert.appcredential.apikey.createdBy The identifier of the user that created the disabled API key. Format: GUID.
alert.appcredential.apikey.createdOn The time, in milliseconds, when the disabled API key was created.
alert.appcredential.apikey.deletedOn The time, in milliseconds, when the disabled API key was deleted.
alert.appcredential.apikey.corsOrigins Comma-separated list of origins associated with the disabled API key.

OAuth:

Message property Description
alert.appcredential.oauthclient.id The identifier of the disabled OAuth credential. Format: GUID.
alert.appcredential.oauthclient.applicationId The identifier of the application associated with the disabled OAuth credential. Format: GUID.
alert.appcredential.oauthclient.enabled Specifies whether the disabled OAuth credential was enabled or disabled. Possible values are: [ "true", "false" ].
alert.appcredential.oauthclient.cert The PEM-encoded certificate associated with the disabled OAuth credential.
alert.appcredential.oauthclient.secret The secret associated with the disabled OAuth credential. Format: GUID.
alert.appcredential.oauthclient.type The client type of the disabled OAuth credential. Possible values are: [ "public", "confidential" ].
alert.appcredential.oauthclient.createdBy The identifier of the user that created the disabled OAuth credential. Format: GUID.
alert.appcredential.oauthclient.createdOn The time, in milliseconds, when the disabled OAuth credential was created.
alert.appcredential.oauthclient.corsOrigins Comma-separated list of origins associated with the disabled OAuth credential.
alert.appcredential.oauthclient.redirectUrls Comma-separated list of redirect URLs associated with the disabled OAuth credential.

External:

Message property Description
alert.appcredential.externalclient.id The identifier of the disabled external credential. Format: GUID.
alert.appcredential.externalclient.clientId The client identifier associated with the disabled external credential. Format: GUID.
alert.appcredential.externalclient.internalClientId
alert.appcredential.externalclient.applicationId The identifier of the application associated with the disabled external credential. Format: GUID.
alert.appcredential.externalclient.enabled Specifies whether the disabled external credential was enabled or disabled. Possible values are: [ "true", "false" ].
alert.appcredential.externalclient.createdBy The identifier of the user that created the disabled external credential. Format: GUID.
alert.appcredential.externalclient.createdOn The time, in milliseconds, when the disabled external credential was created.
alert.appcredential.externalclient.corsOrigins Comma-separated list of origins associated with the disabled external credential.