PingOne Platform APIs

Alerting

The Alerting service delivers warnings to administrators' email addresses regarding changes in resource states that can cause service disruptions. By default, each alert is sent only once. The Alerting service filters out any duplicate alerts.

For administrators to receive these alerts, you must configure the alert channel to use for each environment. Currently, email is the only supported type of alert channel. Use the Alerting service endpoints to configure the alert channel.

Administrators can also configure Alerting preferences in the PingOne admin console.

Assigning admin roles and permissions to this service

Admin role assignments determine access to PingOne APIs. When assigning admin roles to this service, refer to PingOne Permissions by Service for the service-specific permissions.

You can also choose to assign admin roles based on particular service resources. Refer to PingOne Permissions by Resource when assigning admin roles per service resources.

Admin assignments to roles are set by:

Refer to Roles Management for more information.

Alert channel data model

Property Type Required Mutable Description

addresses

String[]

Required

Mutable

The administrator email addresses to send the alerts to.

channelType

String

Required

Mutable

Alert channel type. Currently, this must be EMAIL.

alertName

String

Optional

Mutable

The name to assign to the alert channel.

environment.id

String

Required

Immutable

Unique ID of the environment.

id

String

N/A

Read-only

Unique ID of the alert channel.

includeSeverities

String[]

Optional

Mutable

Filters alerts by severity. If empty, all severities are included. Possible values are INFO, WARNING, and ERROR.

includeAlertTypes

String[]

Optional

Mutable

Use the includeAlertTypes array to specify the alert types you want to create. If empty, all alert types are included. Possible values are: CERTIFICATE_EXPIRED, CERTIFICATE_EXPIRING, GATEWAY_ERROR_ALERT, GATEWAY_INFO_ALERT, GATEWAY_WARNING_ALERT, GATEWAY_VERSION_DEPRECATED, GATEWAY_VERSION_DEPRECATING , KEY_PAIR_EXPIRED, KEY_PAIR_EXPIRING, LICENSE_90_PERCENT_USER_SOFT_LIMIT, LICENSE_ENTITLEMENT_80_PERCENT_EXCEEDED, LICENSE_ENTITLEMENT_90_PERCENT_EXCEEDED, LICENSE_ENTITLEMENT_EXCEEDED, LICENSE_EXPIRED, LICENSE_EXPIRING, LICENSE_ROTATED, LICENSE_USER_HARD_LIMIT_EXCEEDED, LICENSE_USER_SOFT_LIMIT_EXCEEDED, RATE_LIMIT_EXCEEDED, RATE_LIMIT_WARNING, RISK_CONFIGURATION, SUSPICIOUS_TRAFFIC.

Alert events generated

Refer to Audit Reporting Events for the events generated.

Response codes

Code Message

200

Successful operation.

201

Successfully created.

204

Successfully removed. No content.

400

The request could not be completed.

401

You do not have access to this resource.

404

The requested resource was not found.

Alert errors

In addition to the general error codes, alert channel operations can return the following errors:

HTTP status Top‑level code Detail code When it happens and what the response contains

400

INVALID_DATA

INVALID_VALUE

Message: The request could not be completed. One or more validation errors were in the request.

When and details

When: A POST or PUT /alertChannels request includes an alert type that does not exist in includeAlertTypes or excludeAlertTypes

Details: Describes the failing property: Invalid alert type(s): <alertTypes> with the comma‑separated list of unrecognized types, on the includeAlertTypes or excludeAlertTypes target

400

INVALID_DATA

EMPTY_VALUE or INVALID_VALUE

Message: Validation Error : [<property> <message>]

When and details

When: A POST or PUT /alertChannels request omits the required addresses property, supplies an empty addresses set, or includes an address that is not a valid email address

Details: Describes the failing property: addresses must not be null for an omitted addresses, must not be empty for an empty addresses set, or must be a well-formed email address for an addresses entry that is not a valid email address, for example Validation Error : [addresses must not be null].

400

INVALID_DATA

None

Message: Alert type 'EVENT_DELIVERY_FAILED' is not enabled. Requires feature flag 'paxp-330_test_connection_for_webhooks'.

When and details

When: A POST or PUT /alertChannels request includes EVENT_DELIVERY_FAILED in includeAlertTypes or excludeAlertTypes when the event delivery failure alert feature flag is off for the environment

Details: None. The response has no details array.

400

INVALID_REQUEST

INVALID_VALUE

Message: The request could not be completed. The request was malformed or invalid.

When and details

When: A path identifier cannot be parsed as a UUID, or the request body cannot be deserialized, for example an invalid includeSeverities value or a property with the wrong JSON type

Details: For a JSON field conversion error, the target is the field path and the detail message is Invalid value for attribute.. Otherwise no detail is returned. The same handler also covers a channelType value that does not name a registered subtype, which returns the custom channel‑type message instead.

400

INVALID_REQUEST

None

Message: Invalid channelType '<channelType>'. Must be one of: EMAIL

When and details

When: A POST or PUT /alertChannels request supplies a channelType value that is not a known channel type, such as SMS

Details: None. The invalid channel‑type rejection carries the INVALID_REQUEST top‑level code with no detail, while other JSON deserialization failures keep the INVALID_VALUE detail structure.

403

ACCESS_FAILED

None

Message: You do not have permissions or are not licensed to make this request.

When and details

When: The actor lacks the alerting:read:channel permission (GET operations), the alerting:create:channel permission (POST), the alerting:update:channel permission (PUT), or the alerting:delete:channel permission (DELETE)

Details: None.

404

NOT_FOUND

None

Message: AlertChannel not found. EnvironmentId: <environmentId>, AlertChannelId: <channelId>

When and details

When: GET, PUT, or DELETE /alertChannels/{channelId} references an alert channel that does not exist in the environment

Details: None. The service‑specific not‑found message replaces the standard NOT_FOUND default message.