Risk Events API

Early Access

The Okta Risk Events API provides the ability for third-party Risk Providers to send Risk Events to Okta.

Get Started

Explore the Risk Events API: (opens new window)

See Third-party risk provider integration overview for guidance on integrating third-party risk providers with Okta.

Risk Events Operations

The Risk Events API has the following operations:

• Send Risk Events

Send Risk Events

POST /api/v1/risk/events/ip

A Risk Provider can send Risk Events to Okta using this API. This API has a rate limit of 30 requests per minute. The caller should include multiple Risk Events in a single payload to reduce the number of API calls. If a client has more risk signals to send than what the API supports, we recommend prioritizing posting high risk signals.

Request body

The request body should include an array of Risk Events. A maximum of 20 events can be included in a request. Each Risk Event can include the following properties:

Property	Type	Description
timestamp	String	Time stamp at which the the event is produced (Expressed as a UTC time zone using ISO 8601 format: yyyy-MM-dd'T'HH:mm:ss.SSS'Z'). This is an optional field.
expiresAt	String	Time stamp at which the event expires (Expressed as a UTC time zone using ISO 8601 format: yyyy-MM-dd'T'HH:mm:ss.SSS'Z'). If this optional field is not included, Okta automatically expires the event 24 hours after the event is consumed.
subjects	List	List of Risk Subjects. A max of 50 subjects can be included in an event

Response body

Http 202 (Accepted) is returned if the request is successful. If there are validation errors, the API returns a 400.

Request example

This request sends Risk Events to Okta

curl -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${access_token}" \
-d '[
      {
       "timestamp": "2021-01-20T00:00:00.001Z",
       "subjects": [
          {
            "ip": "6.7.6.7",
            "riskLevel": "MEDIUM"
          },
          {
            "ip": "1.1.1.1",
            "riskLevel": "HIGH" ,
            "message": "Detected Attack tooling and suspicious activity"
          }
        ]
      },
      {
       "timestamp": "2021-01-20T01:00:00.001Z",
       "subjects": [
          {
            "ip": "6.7.6.7",
            "riskLevel": "LOW"
          },
          {
            "ip": "2.2.2.2",
            "riskLevel": "HIGH"
          }
        ]
      }
]' "https://${yourOktaDomain}/api/v1/risk/events/ip"

Response example

HTTP/1.1 202 Accepted

Risk Events objects

Risk Event object

The Risk Event object has the following properties:

Property	Type	Description
timestamp	String	Time stamp at which the event is produced (Expressed as a UTC time zone using ISO 8601 format: yyyy-MM-dd'T'HH:mm:ss.SSS'Z'). This is an optional field.
expiresAt	String	Time stamp at which the event expires (Expressed as a UTC time zone using ISO 8601 format: yyyy-MM-dd'T'HH:mm:ss.SSS'Z'). If this optional field is not included, Okta automatically expires the event 24 hours after the event is consumed.
subjects	List	List of Risk Subjects

Risk Event example

{
       "timestamp": "2021-01-20T00:00:00.001Z",
       "subjects": [
          {
            "ip": "6.7.6.7",
            "riskLevel": "MEDIUM"
          },
          {
            "ip": "1.1.1.1",
            "riskLevel": "HIGH" ,
            "message": "Detected Attack tooling and suspicious activity"
          }
        ]
}

Risk Subject object

The Risk Subject object has the following properties:

Property	Type	Description
ip	String	The IP address. This is a required field and should either be an IpV6 or IpV4 address.
riskLevel	String	The risk level associated with the IP. The values can be LOW, MEDIUM, or HIGH. This is a required field.
message	String	Any additional message that the provider can send specifying the reason for the risk level of the IP. This is an optional field with a maximum of 512 characters. The allowed characters are alphabetic, numeric, ., _, and -.

Risk Event example

{
    "ip": "6.7.6.7",
    "riskLevel": "MEDIUM",
    "message": "none"
}