This page describes the Event resource returned by the API v2 Events endpoints and how v2 differs from API v1 Events.
There are three endpoints in the v2 Events API:
- List Event Types – the catalogue of event types. Each entry's
idis the value that appears asevent_type_idon events and in the List Events filter. - List Events – search and page through the events in your account.
- Get Event – return a single event by its
id.
Both List Events and List Event Types return items that have an id attribute, but they are different things. An event’s id uniquely identifies one thing that happened at one point in time, and is the value to pass to Get Event. The event_type_id on an event (and the id returned by List Event Types) identifies a kind of event, such as a login or a user creation. You can browse the full list with the Event Type Lookup tool.
Event-related dates and times use the Coordinated Universal Time (UTC) ISO8601 format: YYYY-MM-DDThh:mm:ss.mscZ. For example: 2016-01-21T09:20:15.990Z.
Differences from API v1
Why use v2?
/api/2/eventsis served by a dedicated events service. It uses cursor-based (keyset) pagination, so every page costs the same regardless of how deep into the result set you are. The v1 endpoint has to read and discard every earlier event on each page, which makes deep pagination progressively slower and can time out on large accounts.
| Area | API v1 (/api/1/events) | API v2 (/api/2/events) |
|---|---|---|
Response envelope | Wrapped in a | No |
Pagination | Offset-based under the hood. Each page re-reads everything before it, so deep pages are slow. | Cursor-based. Pass |
Ordering | Configurable with | Always newest first ( |
Field selection |
| Not supported. Every event is returned in full. |
Filters |
| Everything v1 supports except |
Multiple event types | Comma-separated: | Either form: |
Page size | Up to 50 per page. | Default 50, up to 100 per page ( |
Required scope |
| Same as v1. |
Errors |
| Standard v2 error object: |
Event Resource
Important: The user_name and actor_user_name elements refer to the first and last name of the relevant user, not to their username in OneLogin. If their first and last name user attributes are empty, these elements return the user’s email address instead.
| Element | Data Type | Description |
|---|---|---|
id | Integer | Event's unique ID in OneLogin. Autogenerated by OneLogin. Pass this value to Get Event. |
created_at | String | ISO8601 time and date at which the event was created. This value is autogenerated by OneLogin. |
account_id | Integer | Account that triggered the event. |
user_id | Integer | ID of the user that was acted upon to trigger the event. |
user_name | String | First and last name of the user that was acted upon to trigger the event. |
event_type_id | Integer | Type of event triggered. See List Event Types. |
notes | String | More details about the event. |
custom_message | String | More details about the event. |
ipaddr | String | Client IP address reported by the request, normally the first address in its |
proxy_ip | String | Public IP address that opened the connection to OneLogin, recorded only when it differs from |
actor_user_id | Integer | ID of the user whose action triggered the event. |
actor_user_name | String | First and last name of the user whose action triggered the event. |
actor_system | String | Acting system that triggered the event when the actor is not a user. |
assuming_acting_user_id | Integer | ID of the user who assumed the role of the acting user to trigger the event, if applicable. |
app_id | Integer | ID of the app involved in the event, if applicable. |
app_name | String | Name of the app involved in the event, if applicable. |
role_id | Integer | ID of a role involved in the event. |
role_name | String | Name of a role involved in the event. |
group_id | Integer | ID of a group involved in the event. |
group_name | String | Name of a group involved in the event. |
policy_id | Integer | ID of the policy involved in the event. |
policy_name | String | Name of the policy involved in the event. |
otp_device_id | Integer | ID of a device involved in the event. |
otp_device_name | String | Name of a device involved in the event. |
directory_id | Integer | ID of the directory involved in the event, if applicable. |
directory_sync_run_id | Integer | Directory sync run ID. |
resolution | Integer | Resolution of an exception event: |
client_id | String | Client ID used to generate the access token that made the API call that generated the event. When the change was made through the API with an API credential, this is that credential's client ID, a 64-character hexadecimal string, and |
api_credential_name | String | Name of the API credential involved in the event, if applicable. What it refers to depends on the event: When the change was made through the API with an API credential, it is the name of the credential that made the change, the same credential as On the API credential events The name is saved on the event when the event is recorded, so renaming the credential later does not change existing events. |
resource_type_id | Integer | ID of the resource (user, role, group, and so forth) associated with the event. |
error_description | String | Provisioning error details, if applicable. |
risk_score | Integer | Vigilance AI risk score (0–100) calculated for the event, if applicable. |
risk_reasons | String | Human-readable reasons behind the risk score, if applicable. |
risk_cookie_id | String | ID of the risk cookie associated with the event, if applicable. |
browser_fingerprint | String | Fingerprint of the browser used to trigger the event, if applicable. |
privilege_id | Integer | ID of the privilege associated with the event, if applicable. Always |
privilege_name | String | Name of the privilege associated with the event, if applicable. |
Client IP and connection IP
An event triggered by a web request records up to two IP addresses:
ipaddris the client address the request reports, normally the first address in itsX-Forwarded-Forheader. The device, or any proxy between it and OneLogin, can set that header.proxy_ipis the address that actually connected to OneLogin. It is recorded only when it differs fromipaddr.
When a device connects to OneLogin directly and sends no X-Forwarded-For header of its own, the two addresses are the same, so only ipaddr is set and proxy_ip is null. That is the case for most events, so a mostly empty proxy_ip is expected.
proxy_ip is set when the request’s X-Forwarded-For header names a different client address. Usually a proxy between the device and OneLogin added it. Common causes are a corporate proxy or secure web gateway, and services hosted in a public cloud that relay requests. In those cases ipaddr is often the device’s internal or home address, and proxy_ip is the proxy’s public address. A VPN or NAT gateway that does not add the header changes both addresses together, so on its own it does not set proxy_ip. A client, such as a script, can also send its own X-Forwarded-For header with any value, which sets proxy_ip with no proxy involved. A populated proxy_ip only records that the two addresses differed. It is not the result of a proxy-detection or threat-intelligence lookup.
The Events page in the OneLogin admin portal shows proxy_ip as Proxy IP address. To find every event involving an address, filter List Events by ip, which matches either field.
For sign-ins through the OneLogin login page, Vigilance AI evaluates the address that connected to OneLogin, not ipaddr, when it calculates risk_score. When proxy_ip is set, risk_reasons can therefore reflect an address or location that does not match ipaddr.
Using
proxy_ipto spot adversary-in-the-middle phishingAn adversary-in-the-middle (AitM) phishing site relays the user’s sign-in to OneLogin through the attacker’s own server. That server can pass the victim’s real address in
X-Forwarded-For, so the event’sipaddrlooks routine whileproxy_ipshows the attacker’s server, often an address in a public cloud provider’s range. A sign-in whoseproxy_ipis not one of your organization’s own proxies or secure web gateways is worth investigating. Both fields are available from the Events API and event webhooks, so you can alert on them in your SIEM.
Changes made with an API credential
When a change is made through the API with an access token generated from an API credential, the event records the credential, not a user, as the actor:
actor_user_idisnull.actor_systemandactor_user_nameare bothAPI.api_credential_nameis the credential’s name andclient_idis its client ID.
For example, if an API credential named “HR Sync” suspends a user, the event includes:
{
"event_type_id": 551,
"user_name": "Jane Doe",
"actor_user_id": null,
"actor_system": "API",
"actor_user_name": "API",
"client_id": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
"api_credential_name": "HR Sync"
}The Events page in the OneLogin admin portal shows the same event as “Jane Doe suspended by API credential HR Sync via API”.
To find the events recorded for one credential, filter List Events by client_id.
Events recorded before October 30, 2026
Before October 30, 2026, some changes made through the API with an API credential, such as suspending, reactivating, locking, or unlocking a user, were recorded with the OneLogin account owner as the actor in
actor_user_idandactor_user_name. Others recordedAPIas the actor but did not name the credential. Events recorded from that date carry the credential inapi_credential_nameandclient_idinstead. Existing events were not changed, so if you collect events in a SIEM or through this API, older API changes can still name the account owner as the actor.Not every API endpoint records the credential yet, and more are being updated. Until an endpoint is updated, its events keep their earlier form.
Have a Question?
Found a problem or a bug? Submit a support ticket.
Looking for walkthroughs or how-to guides? Check out our Knowledge Base.
Have a product idea or request? Share it in our Ideas Portal.