Event Resource

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 id is the value that appears as event_type_id on 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/events is 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.

AreaAPI v1 (/api/1/events)API v2 (/api/2/events)

Response envelope

Wrapped in a status object; the resource is always inside a data array.

No status object. List Events returns { "data": [...], "pagination": {...} }; Get Event returns the event object itself; List Event Types returns a plain array.

Pagination

Offset-based under the hood. Each page re-reads everything before it, so deep pages are slow.

Cursor-based. Pass next_cursor from the previous response as after_cursor. Constant cost per page. There is no before_cursor; page forward only.

Ordering

Configurable with sort.

Always newest first (created_at descending). There is no sort parameter.

Field selection

fields parameter.

Not supported. Every event is returned in full.

Filters

event_type_id, user_id, directory_id, client_id, resolution, since, until, id, created_at.

Everything v1 supports except id and created_at, plus app_id, role_id, group_id, resource_type_id, actor_system, ip, risk_score_min, risk_score_max, and free-text search. See List Events.

Multiple event types

Comma-separated: event_type_id=8,13

Either form: event_type_id=8,13 or event_type_id[]=8&event_type_id[]=13

Page size

Up to 50 per page.

Default 50, up to 100 per page (limit).

Required scope

Read Users, Manage users, Read All, or Manage All.

Same as v1.

Errors

status object with error: true.

Standard v2 error object: { "name": "...", "message": "...", "statusCode": ... }. Invalid query parameters return 400 with the reason in message.

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.

ElementData TypeDescription

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 X-Forwarded-For header. The client or any proxy between it and OneLogin can set that header, so treat this value as reported, not verified. See Client IP and connection IP.

proxy_ip

String

Public IP address that opened the connection to OneLogin, recorded only when it differs from ipaddr. A value here means the request reported a different client address, usually because a proxy between the client and OneLogin, such as a secure web gateway or a cloud-hosted relay, added one. A client can also send that header itself. It is not the result of any proxy-detection or threat-intelligence lookup. null for most events, where both addresses are the same. See Client IP and connection IP.

actor_user_id

Integer

ID of the user whose action triggered the event. null when the change was made through the API with an API credential, because no user made it. See Changes made with an API credential.

actor_user_name

String

First and last name of the user whose action triggered the event. API when the change was made through the API with an API credential.

actor_system

String

Acting system that triggered the event when the actor is not a user. API when the change was made through the API with an API credential; the credential itself is identified by api_credential_name and client_id.

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: 0 unresolved, 1 ignored, 2 unlocked. null for events that are not exceptions.

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 is its name.

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 client_id.

On the API credential events API_CREDENTIAL_CREATED (179), API_CREDENTIAL_DELETED (180), API_CREDENTIAL_ENABLED (181), and API_CREDENTIAL_DISABLED (182), it is the name of the credential that was created, deleted, enabled, or disabled, not the actor. Use the actor elements to see who made that change.

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 null for delegated privilege events (2100–2113).

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:

  • ipaddr is the client address the request reports, normally the first address in its X-Forwarded-For header. The device, or any proxy between it and OneLogin, can set that header.
  • proxy_ip is the address that actually connected to OneLogin. It is recorded only when it differs from ipaddr.

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_ip to spot adversary-in-the-middle phishing

An 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’s ipaddr looks routine while proxy_ip shows the attacker’s server, often an address in a public cloud provider’s range. A sign-in whose proxy_ip is 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_id is null.
  • actor_system and actor_user_name are both API.
  • api_credential_name is the credential’s name and client_id is 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_id and actor_user_name. Others recorded API as the actor but did not name the credential. Events recorded from that date carry the credential in api_credential_name and client_id instead. 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.