On this page
Risk Events API
Early AccessThe 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
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"
}