Is it easy or difficult to use our developer documentation? Let us know in this short survey ↗

On this page

System Log API

The Okta System Log records system events that are related to your organization in order to provide an audit trail that can be used to understand platform activity and to diagnose problems.

The Okta System Log API provides near real-time, read-only access to your organization's system log and is the programmatic counterpart of the System Log UI (opens new window).

The terms "event" and "log event" are often used interchangeably. In the context of this API, an "event" is an occurrence of interest within the system, and a "log" or "log event" is the recorded fact.

Several common use cases for the System Log API include:

  • Ingesting events into a Security Information and Event Management (SIEM) platform for security analysis and correlation with other relevant security events
  • Ingesting events into a data warehouse or data lake for user activity analysis or complex security detections
  • Ingesting events into an observability system for application monitoring and debugging
  • As a source for customer business logic to react to events asynchronously, such as a periodic collection of new user IDs when self-service registration is enabled.

The System Log API isn't intended for use as a Database as a Service (DBaaS) or to serve data directly to downstream consumers without an intermediate data store.

Note: Some of the curl code examples on this page include SSWS API token authentication. However, Okta recommends using scoped OAuth 2.0 and OIDC access tokens to authenticate with Okta management APIs. OAuth 2.0 and OIDC access tokens provide fine-grain control over the bearer's actions on specific endpoints. See Okta API authentication methods.

Get started

The System Log API has one endpoint:

GET /api/v1/logs

Run in Postman (opens new window)

This collection resource is backed by a LogEvent object and associated event types.

See Examples for ways you can use the System Log API. See Useful System Log Queries (opens new window) for common use cases.

LogEvent object

Each LogEvent object describes a single logged action or "event" that is performed by a set of actors for a set of targets.

Example LogEvent object

{
  "version": "0",
  "severity": "INFO",
  "client": {
    "zone": "OFF_NETWORK",
    "device": "Unknown",
    "userAgent": {
      "os": "Unknown",
      "browser": "UNKNOWN",
      "rawUserAgent": "UNKNOWN-DOWNLOAD"
    },
    "ipAddress": "12.97.85.90"
  },
  "device": {
    "id": "guob5wtu7rBggkg9G1d7",
    "name": "MacBookPro16,1",
    "os_platform": "OSX",
    "os_version": "14.3.0",
    "managed": false,
    "registered": true,
    "device_integrator": null,
    "disk_encryption_type": "ALL_INTERNAL_VOLUMES",
    "screen_lock_type": "BIOMETRIC",
    "jailbreak": null,
    "secure_hardware_present": true
  },
  "actor": {
    "id": "00u1qw1mqitPHM8AJ0g7",
    "type": "User",
    "alternateId": "admin@example.com",
    "displayName": "John Doe"
  },
  "outcome": {
    "result": "SUCCESS"
  },
  "uuid": "f790999f-fe87-467a-9880-6982a583986c",
  "published": "2017-09-31T22:23:07.777Z",
  "eventType": "user.session.start",
  "displayMessage": "User login to Okta",
  "transaction": {
    "type": "WEB",
    "id": "V04Oy4ubUOc5UuG6s9DyNQAABtc"
  },
  "debugContext": {
    "debugData": {
      "requestUri": "/login/do-login"
    }
  },
  "legacyEventType": "core.user_auth.login_success",
  "authenticationContext": {
    "authenticationStep": 0,
    "externalSessionId": "1013FfF-DKQSvCI4RVXChzX-w"
  }
}

LogEvent object annotated example

{
  "uuid": Randomly generated String, Required
  "published": ISO8601 string for timestamp, Required
  "eventType": String, Required
  "version": String, Required
  "severity": String, one of DEBUG, INFO, WARN, ERROR, Required
  "legacyEventType": String, Optional
  "displayMessage": String, Optional
  "actor": { Object, Required
      "id": String, Required
      "type": String, Required
      "alternateId": String, Optional
      "displayName": String, Optional
      "detailEntry": {
          String -> String/Resource Map
      }
},
  "client": { Object, Optional
     "userAgent": { Object, Optional
          "rawUserAgent": String, Optional
          "os": String, Optional
          "browser": String, Optional
     },
     "geographicalContext": { Object, Optional
          "geolocation": { Object, Optional
               "lat": Double, Optional
               "lon": Double, Optional
          }
          "city": String, Optional
          "state": String, Optional
          "country": String, Optional
          "postalCode": String, Optional
     },
     "zone": String, Optional
     "ipAddress": String, Optional
     "device": String, Optional
     "id": String, Optional
},
  "device": { Object, Optional
     "id": String, Optional
     "name": String, Optional
     "os_platform": String, Optional
     "os_version": String, Optional
     "managed": Boolean, Optional
     "registered": Boolean, Optional
     "device_integrator": Object, Optional
     "disk_encryption_type": String, one of: NONE, FULL, SYSTEM_VOLUME, ALL_INTERNAL_VALUES, and USER, Optional
     "screen_lock_type": String, one of: NONE, PASSCODE, and BIOMETRIC, Optional
     "jailbreak": Boolean, Optional
     "secure_hardware_present": Boolean, Optional
},
  "outcome": { Object, Optional
     "result": String, one of: SUCCESS, FAILURE, SKIPPED, ALLOW, DENY, CHALLENGE, UNKNOWN, Required
     "reason": String, Optional
},
  "target": [ List of Objects of the form:
    {
       "id": String, Required
       "type": String, Required
       "alternateId": String, Optional
       "displayName": String, Optional
       "detailEntry" = {
         String -> String/Resource Map
        }
       "changeDetails" = {
          "from:": {String -> String/Resource Map
          }
          "to:": {String -> String/Resource Map
          }
        }
     }
],
  "transaction": { Object, Optional
     "id": String, Optional
     "type": String one of "WEB", "JOB", Optional
     "detail" = {
          String -> String/Resource Map
     }
},
  "debugContext": { Object, Optional
     "debugData": {
          String -> String/Resource Map
          "requestUri": "/api/1/devtools/global/test/orgs/specific"
          "originalPrincipal": {
             "id": "00ujchcbjpltartYI0g3",
             "type": "User",
             "alternateId": "admin@example.com",
             "displayName": "Piras Add-min"
          },
     }
},
  "authenticationContext": { Object, Optional
     "authenticationProvider": String one of OKTA_AUTHENTICATION_PROVIDER, ACTIVE_DIRECTORY, LDAP, FEDERATION,
            SOCIAL, FACTOR_PROVIDER, Optional
     "credentialProvider": String one of OKTA_CREDENTIAL_PROVIDER, RSA, SYMANTEC, GOOGLE, DUO, YUBIKEY, Optional
     "credentialType": String one of OTP, SMS, PASSWORD, ASSERTION, IWA, EMAIL, OAUTH2, JWT, CERTIFICATE, PRE_SHARED_SYMMETRIC_KEY, OKTA_CLIENT_SESSION, DEVICE_UDID,     Optional
     "issuer": Object, Optional {
        "id": String, Optional
        "type": String Optional
      }
      "externalSessionId": String, Optional
      "interface": String, Optional i.e. Outlook, Office365, wsTrust
},
  "securityContext": { Object, Optional
     "asNumber": Integer, Optional
     "asOrg": String, Optional
     "isp": String, Optional
     "domain": String, Optional
     "isProxy": Boolean, Optional
},
  "request": { Object, Optional
     "ipChain": List of objects of the form [{
          "ip": String, Optional
          "geographicalContext": { Object, Optional
              "geolocation": { Object, Optional
                  "lat":Double, Optional
                  "lon": Double, Optional
              }
               "city": String, Optional
               "state": String, Optional
               "country": String, Optional
               "postalCode": String, Optional
          },
          "version": String, one of V4, V6 Optional
          "source": String, Optional
     }], Optional
  }
}

Attributes

LogEvent objects are read-only. The following properties are available:

Property Description DataType Nullable Unique Readonly MinLength MaxLength
uuid Unique identifier for an individual event String FALSE TRUE TRUE
published Timestamp when the event is published Date FALSE FALSE TRUE 1 255
eventType Type of event that is published String FALSE FALSE TRUE 1 255
version Versioning indicator String FALSE FALSE TRUE 1 255
severity Indicates how severe the event is: DEBUG, INFO, WARN, ERROR String FALSE FALSE TRUE 1 255
legacyEventType Associated Events API Action objectType attribute value String TRUE FALSE TRUE 1 255
displayMessage The display message for an event String TRUE FALSE TRUE 1 255
actor Describes the entity that performs an action Actor object TRUE FALSE TRUE
client The client that requests an action Client object TRUE FALSE TRUE
request The request that initiates an action Request object TRUE FALSE TRUE
outcome The outcome of an action Outcome object TRUE FALSE TRUE
target Zero or more targets of an action Array of Target object TRUE FALSE TRUE
transaction The transaction details of an action Transaction object TRUE FALSE TRUE
debugContext The debug request data of an action DebugContext object TRUE FALSE TRUE
authenticationContext The authentication data of an action AuthenticationContext object TRUE FALSE TRUE
securityContext The security data of an action SecurityContext object TRUE FALSE TRUE

NOTE: The actor or target of an event is dependent on the action that is performed. All events have actors but not all have targets.

NOTE: See Event Correlation for information on authenticationContext.externalSessionId and transaction.id.

Actor object

Describes the user, app, client, or other entity (actor) who performs an action on a target

Property Description DataType Nullable
id ID of the actor String FALSE
type Type of actor String FALSE
alternateId Alternative ID of the actor String TRUE
displayName Display name of the actor String TRUE
detailEntry Details about the actor Map[String->Object] TRUE

Target object

The entity that an actor performs an action on. Targets can be anything, such as an app user, a sign-in token, or anything else.

Property Description DataType Nullable
id ID of a target String FALSE
type Type of target String FALSE
alternateId Alternative ID of a target String TRUE
displayName Display name of a target String TRUE
detailEntry Details on a target Map[String->Object] TRUE
changeDetails Details on the target's changes Map[String->Object] TRUE
{
    "id": "00u3gjksoiRGRAZHLSYV",
    "displayName": "Jon Stewart",
    "alternateId": "00uKrs9rsRSAXN",
    "login": "jon@example.com",
    "type": "User"
}

changeDetails property

The changeDetails property of the target object defines the change of state of an entity within Okta. Each changeDetails property contains a to and from object that defines the change. Not all event types support the changeDetails property, and not all target objects contain the changeDetails property.

"target": [
  {
    "id": "0oaabcd1234",
    "type": "AppInstance",
    "alternateId": "Workday",
    "displayName": "Workday",
    "detailEntry": null,
    "changeDetails": {
      "from": {
        "vpnLocationOptions": "DISABLED",
        "vpnSettingsZones": {
          "include": [],
          "exclude": []
        }
      },
      "to": {
        "message": "You must a use VPN to connect to this application",
        "vpnLocationOptions": "ZONE",
        "vpnSettingsZones": {
          "include": [
            "ALL_ZONES"
          ],
          "exclude": []
        }
      }
    }
  }
]

Note: When querying the changeDetails property, you can't search on the to or from objects alone. You must include a property within the object.

Client object

When an event is triggered by an HTTP request, the client object describes the client (opens new window) that issues the HTTP request. For instance, the web browser is the client when a user accesses Okta. When this request is received and processed, a sign-in event is fired. When the event isn't sourced to an HTTP request, such as an automatic update, the client object field is blank.

Property Description DataType Nullable
id For OAuth requests, this is the ID of the OAuth client (opens new window) making the request. For SSWS token requests, this is the ID of the agent making the request. String TRUE
userAgent The user agent (opens new window) that's used by an actor to perform an action UserAgent object TRUE
geographicalContext The physical location where the client is making its request from GeographicalContext object TRUE
zone The name of the Zone (opens new window) that the client's location is mapped to String TRUE
ipAddress IP address that the client is making its request from String TRUE
device Type of device that the client operates from (for example, Computer) String TRUE

Device object

The entity that describes a device enrolled with passwordless authentication using Okta Verify.

Property Description DataType Nullable
id ID of the device String FALSE
name Name of the device String FALSE
os_platform Operating system of the device String TRUE
os_version Operating system version of the device String TRUE
managed Indicates if the device is configured for device management and is registered with Okta Boolean TRUE
registered Indicates if the device is registered with an Okta org and is bound to an Okta Verify instance on the device Boolean TRUE
device_integrator The integration platform or software used with the device Object TRUE
disk_encryption_type The amount of disk encryption for a device. Values can be: NONE, FULL, SYSTEM_VOLUME, ALL_INTERNAL_VALUES, and USER. Enum TRUE
screen_lock_type The availability of a screen lock on the device. Values can be: NONE, PASSCODE, and BIOMETRIC. Enum TRUE
jailbreak If the device has removed software restrictions Boolean TRUE
secure_hardware_present The availability of hardware security on the device Boolean TRUE
{
  "id": "guob5wtu7rAggkg9G1d7",
  "name": "MacBookPro16,1",
  "os_platform": "OSX",
  "os_version": "14.3.0",
  "managed": false,
  "registered": true,
  "device_integrator": null,
  "disk_encryption_type": "ALL_INTERNAL_VOLUMES",
  "screen_lock_type": "BIOMETRIC",
  "jailbreak": null,
  "secure_hardware_present": true
}

UserAgent object

"A user agent is software (a software agent) that is acting on behalf of a user." (Definition of User Agent (opens new window))

In the Okta event data object, the UserAgent object provides specifications about the client software that makes event-triggering HTTP requests. User agent identification is often useful for identifying interoperability problems between servers and clients, and also for browser and operating system usage analytics.

Property Description DataType Nullable
Browser If the client is a web browser, this field identifies the type of web browser (for example, CHROME, FIREFOX) String TRUE
OS The operating system that the client runs on (for example, Windows 10) String TRUE
RawUserAgent A raw string representation of the user agent that is formatted according to section 5.5.3 of HTTP/1.1 Semantics and Content (opens new window). Both the browser and the OS fields can be derived from this field. String TRUE

Request object

The Request object describes details that are related to the HTTP request that triggers this event, if available. When the event isn't sourced to an HTTP request, such as an automatic update on the Okta servers, the Request object still exists, but the ipChain field is empty.

Property Description DataType Nullable
ipChain If the incoming request passes through any proxies, the IP addresses of those proxies are stored here in the format: clientIp, proxy1, proxy2, and so on. This field is useful when working with trusted proxies. Array of IpAddress TRUE

GeographicalContext object

Geographical context describes a set of geographic coordinates. In addition to containing latitude and longitude data, the GeographicalContext object also contains address data of postal code-level granularity. Within the Client object, the geographical context refers to the physical location of the client when it sends the request that triggers this event. All Transaction events with type equal to WEB have a geographical context set. Transaction events with type equal to JOB don't have a geographical context set. The geographical context data can be missing if the geographical data for a request can't be resolved.

Property Description DataType Nullable
geolocation Contains the geolocation coordinates (latitude, longitude) Geolocation object TRUE
city The city that encompasses the area that contains the geolocation coordinates, if available (for example, Seattle, San Francisco) String TRUE
state Full name of the state or province that encompasses the area that contains the geolocation coordinates (for example, Montana, Ontario) String TRUE
country Full name of the country that encompasses the area that contains the geolocation coordinates (for example, France, Uganda) String TRUE
postalCode Postal code of the area that encompasses the geolocation coordinates String TRUE

Geolocation object

The latitude and longitude of the geolocation where an action was performed. The object is formatted according to the ISO-6709 (opens new window) standard.

Property Description DataType Nullable
lat Latitude: Uses two digits for the integer part (opens new window) Double FALSE
lon Longitude: Uses three digits for the integer part (opens new window) Double FALSE

Outcome object

Describes the result of an action and the reason for that result.

Property Description DataType Nullable Default MinLength MaxLength
result Result of the action: SUCCESS, FAILURE, SKIPPED, ALLOW, DENY, CHALLENGE, UNKNOWN String FALSE
reason Reason for the result, for example, INVALID_CREDENTIALS String TRUE 1 255

Transaction object

The transaction field contains a Transaction object.

A Transaction object comprises contextual information associated with its respective event. This information is useful for understanding sequences of correlated events (see Event Correlation).

For example, a Transaction object such as the following:

{
    "id": "Wn4f-0RQ8D8lTSLkAmkKdQAADqo",
    "type": "WEB",
    "detail": null
}

indicates that a WEB request with id Wn4f-0RQ8D8lTSLkAmkKdQAADqo has created this event.

A Transaction object with a requestApiTokenId in the detail object, for example:

{
    "id": "YjSlblAAqnKY7CdyCkXNBgAAAIU",
    "type": "WEB",
    "detail": {
        "requestApiTokenId": "00T94e3cn9kSEO3c51s5"
    }
}

indicates that this event was the result of an action performed through an API using the token identified by 00T94e3cn9kSEO3c51s5. The token ID is visible in the Admin Console, Security > API. See API token management (opens new window). For more information on API tokens, see Create an API token.

Property Description DataType Nullable
id Unique identifier for this transaction. String TRUE
type Describes the kind of transaction. WEB indicates a web request. JOB indicates an asynchronous task. String TRUE
detail Details for this transaction. Map[String → Object] TRUE

DebugContext object

For some kinds of events (for example, OLM provisioning, sign-in request, second factor SMS, and so on), the fields that are provided in other response objects aren't sufficient to adequately describe the operations that the event has performed. In such cases, the debugContext object provides a way to store additional information.

For example, an event where a second factor SMS token is sent to a user may have a debugContext that looks like the following:

{
    "debugData": {
        "requestUri": "/api/v1/users/00u3gjksoiRGRAZHLSYV/factors/smsf8luacpZJAva10x45/verify",
        "smsProvider": "TELESIGN",
        "transactionId": "268632458E3C100F5F5F594C6DC689D4"
    }
}

By inspecting the debugData field, you can find the URI that is used to trigger the second factor SMS (/api/v1/users/00u3gjksoiRGRAZHLSYV/factors/smsf8luacpZJAva10x45/verify), the SMS provider (TELESIGN), and the ID used by Telesign to identify this transaction (268632458E3C100F5F5F594C6DC689D4).

If for some reason the information that is needed to implement a feature isn't provided in other response objects, you should scan the debugContext.debugData field for potentially useful fields.

Important: The information contained in debugContext.debugData is intended to add context when troubleshooting customer platform issues. Both key names and values may change from release to release and aren't guaranteed to be stable. Therefore, they shouldn't be viewed as a data contract but as a debugging aid instead.

Property Description DataType Nullable
debugData Dynamic field that contains miscellaneous information that is dependent on the event type Map[String->Object] TRUE

AuthenticationContext object

All authentication relies on validating one or more credentials that prove the authenticity of the actor's identity. Credentials are sometimes provided by the actor, as is the case with passwords, and at other times provided by a third party, and validated by the authentication provider.

The authenticationContext contains metadata about how the actor is authenticated. For example, an authenticationContext for an event, where a user authenticates with Integrated Windows Authentication (IWA), looks like the following:

{
    "authenticationProvider": "ACTIVE_DIRECTORY",
    "authenticationStep": 0,
    "credentialProvider": null,
    "credentialType": "IWA",
    "externalSessionId": "102N1EKyPFERROGvK9wizMAPQ",
    "interface": null,
    "issuer": null
}

In this case, the user enters an IWA credential to authenticate against an Active Directory instance. All of the user's future-generated events in this sign-in session are going to share the same externalSessionId.

Among other operations, this response object can be used to scan for suspicious sign-in activity or perform analytics on user authentication habits (for example, how often authentication scheme X is used versus authentication scheme Y).

Property Description DataType Nullable MinLength MaxLength
authenticationProvider The system that proves the identity of an actor using the credentials provided to it String TRUE
authenticationStep The zero-based step number in the authentication pipeline. Currently unused and always set to 0. Integer TRUE
credentialProvider A credential provider is a software service that manages identities and their associated credentials. When authentication occurs through credentials provided by a credential provider, the credential provider is recorded here. String TRUE
credentialType The underlying technology/scheme used in the credential String TRUE
issuer The specific software entity that creates and issues the credential Issuer object TRUE
externalSessionId A proxy for the actor's session ID (opens new window) String TRUE 1 255
interface The third-party user interface that the actor authenticates through, if any. String TRUE 1 255
Possible values

Some of the previously listed fields have a finite set of possible values.

Property Possible Values
authenticationProvider OKTA_AUTHENTICATION_PROVIDER, ACTIVE_DIRECTORY, LDAP, FEDERATION, SOCIAL, FACTOR_PROVIDER
credentialProvider OKTA_CREDENTIAL_PROVIDER, RSA, SYMANTEC, GOOGLE, DUO, YUBIKEY
credentialType OTP, SMS, PASSWORD, ASSERTION, IWA, EMAIL, OAUTH2, JWT, CERTIFICATE, PRE_SHARED_SYMMETRIC_KEY, OKTA_CLIENT_SESSION, DEVICE_UDID

Issuer object

Describes the issuer of the authorization server when the authentication is performed through OAuth. This is the location where well-known resources regarding the details of the authorization servers are published.

Property Description DataType Nullable
id Varies depending on the type of authentication. If authentication is SAML 2.0, id is the issuer in the SAML assertion. For social login, id is the issuer of the token. String TRUE
type Information on the issuer and source of the SAML assertion or token. String TRUE

SecurityContext object

The securityContext object provides security information that is directly related to the evaluation of the event's IP reputation. IP reputation is a trustworthiness rating that evaluates how likely a sender is to be malicious and is based on the sender's IP address. As the name implies, the securityContext object is useful for security applications-flagging and inspecting suspicious events.

Property Description DataType Nullable
asNumber The Autonomous system (opens new window) number that's associated with the autonomous system the event request was sourced to Integer TRUE
asOrg The organization that is associated with the autonomous system that the event request is sourced to String TRUE
isp The Internet service provider that's used to send the event's request String TRUE
domain The domain name that's associated with the IP address of the inbound event request String TRUE
isProxy Specifies whether an event's request is from a known proxy Bool TRUE

IpAddress object

Describes an IP address used in a request

Property Description DataType Nullable
ip IP address String TRUE
geographicalContext Geographical context of the IP address GeographicalContext object TRUE
version IP address version V4 or V6 TRUE
source Details regarding the source String TRUE

Event types

Event types categorize event instances by action and are recorded in a LogEvent's eventType attribute. They are key to navigating the system log through Expression Filters.

The following sections outline the key event types that are captured by the system log. See Event Types catalog for a complete list.

Application event

Event Description
application.lifecycle.activate An application is activated.
application.lifecycle.create An application is created.
application.lifecycle.deactivate An application is deactivated.
application.lifecycle.delete An application is deleted.
application.lifecycle.update An application is updated.
application.user_membership.add A user is assigned to an application.
application.user_membership.change_username The name of a user who is assigned to an application is changed.
application.user_membership.remove A user is removed from an application.

Group event

Event Description
group.user_membership.add A user is added to a group.
group.user_membership.remove A user is removed from a group.

Policy events

Event Description
policy.lifecycle.activate A lifecycle policy is activated.
policy.lifecycle.create A lifecycle policy is created.
policy.lifecycle.deactivate A lifecycle policy is deactivated.
policy.lifecycle.delete A lifecycle policy is deleted.
policy.lifecycle.update A lifecycle policy is updated.
policy.rule.activate A rule in a policy is activated.
policy.rule.add A rule is added to a policy.
policy.rule.deactivate A rule in a policy is deactivated.
policy.rule.delete A rule is deleted from a policy.
policy.rule.update A rule in a policy is updated.

Policy event details

  • policy.evaluate_sign_on provides context on the values that are used and evaluated in the context of the Okta sign-in policy. For example, you can determine which network zones are matched for this event.
  • For policy.lifecycle and policy.rule events, the corresponding policy is listed in the target object.

Rate limit events

See System Log events for rate limits for information on rate limit event types.

Rate limit warnings are sent at different times, depending on the org type. For One App and Enterprise orgs, the warning is sent when the org is at 60% of its limit.

Note: For orgs created before 2018-05-17, the warning is sent at 90%.

Rate limit violations are sent when a rate limit is exceeded.

Security events

Event Description
security.request.blocked A request is blocked due to a blocklist rule (such as an IP network zone or location rule).

User events

Event Description
user.authentication.sso A user attempts a Single Sign-On (SSO) to an application managed in Okta
user.lifecycle.activate A user account is activated.
user.lifecycle.create A user account is created.
user.lifecycle.deactivate A user account is deactivated.
user.lifecycle.suspend A user account is suspended.
user.lifecycle.unsuspend A user account is moved from suspended status.
user.session.start Okta issues a session to a user who is authenticating.

User event details

user.authentication.sso doesn't capture whether the SSO attempt is successful or has failed, because Okta can't collect the subsequent authentication attempt status from the third-party service.

Event correlation

When looking through the System Log, it is often useful to correlate events so that you can understand the thread of events that have occurred at a particular time.

The LogResponse object offers two identifiers in this respect:

  • authenticationContext.externalSessionId: Identifies events that occurred in the same user session
  • transaction.id: Identifies events that have occurred together as part of an operation (for example, a request to Okta's servers)

Correlating events based on API Token

It may be useful to identify multiple events that are the result of an action made using a specific API token. For example, when investigating a rate limit warning, the events made by a specific token may be helpful in identifying the cause of the warning. The filter filter=transaction.detail.requestApiTokenId eq "00T94e3cn9kSEO3c51s5" returns all events that were the result of an action made using the token 00T94e3cn9kSEO3c51s5, subject to other parameters of the query.

Event correlation example

The following table shows 18 events produced from 13 transactions over six different sessions, all performed by one user.

Note: authenticationContext.externalSessionId is abbreviated to sessionId in this table.

sessionId transaction.id uuid eventType displayMessage
trs5JnlvlaIQTOqOj9imLy7lA WcKPxq1f8QLfFvv3UPHhhgAACGM f24790d0-d324-47f8-aac5-c27a31ab928d user.session.access_admin_app User accessing Okta administrator app
WcKPxq1f8QLfFvv3UPHhhgAACGM ed317758-8776-4240-a540-277c44dcb408 application.lifecycle.update Update application
421c1551-71b2-4ebe-a70d-b5f7d3698429 application.lifecycle.update Update application
06a50bbe-44fd-40de-83e6-2e4cc2a17d16 application.lifecycle.update Update application
trsUz2TG3wKS6ar1lvWzHo71w Wij-6q4YuniRd9yTmWHpfwAAADc 3e240ff4-6af7-47f2-b107-a2ef661ffc01 application.user_membership.change_username Change users application username
572b05e9-b6be-4dfe-8bc3-01bb3a5a1af5 application.user_membership.add Add user to application membership
30f29bbf-3218-429b-827a-0a93809591db application.user_membership.remove Remove users application membership
Wij-964YuniRd9yTmWHu1AAAAEA 5f98d062-05a9-4ede-89a0-8a2ce27efdd4 user.session.access_admin_app User accessing Okta administrator app
Wij-95eCbHF7In2MKNavlgAAD9I 45f71ac2-e8b2-4c19-b4cc-d2560108c889 application.lifecycle.update Update application
46b85d65-01c6-44d2-86d2-25704804b1c5 application.lifecycle.update Update application
102GALFw8CzRT2KXoqnca8Jdg Wij-AJeCbHF7In2MKNaOpAAAEC4 b9ab9263-a4ae-4780-9981-377ec8f2da86 user.session.start User login to Okta
Wij-7q4YuniRd9yTmWHrBQAAAKQ ff325685-0220-484c-82cf-5f8dc596acbe user.authentication.sso User single sign on to app
trsf8nlpDJZTZeFlcc8nszbjw Wij-7a4YuniRd9yTmWHqqAAAAKY 5526a4c4-7f68-4b2a-bab7-2d10ebaeeb1c mim.checkOSXAccessEligibility.true blank
Wij-764YuniRd9yTmWHrkAAAAGw 232774ba-8feb-4b00-a732-e0ec99a24434 user.session.start User login to Okta
trswPONv4wIRaKDNWVVcmtceg Wij-6K4YuniRd9yTmWHo9wAAAAY d31d819a-1427-45b0-a8b4-8a8fb40c72f1 user.session.start User login to Okta
Wij-564YuniRd9yTmWHoaQAAAII 0cc6f4c8-9b91-4a70-b5c4-09d6ad159d32 mim.checkOSXAccessEligibility.true blank
Wij-2q4YuniRd9yTmWHjRAAAADA 92606da8-7eeb-4ad7-8ffb-502dd0ec64cc user.authentication.sso User single sign on to app
null Wm@-R2s5lEMbNIB03krtvAAACyo 566671be-ec0b-400d-ad2e-6fc73ed12fb1 user.session.start User login to Okta

As evidenced by the null authenticationContext.externalSessionId field in the last row, neither transaction.id nor uuid maintain a many-to-one relationship with authenticationContext.externalSessionId. In this particular case, the null authenticationContext.externalSessionId field can be explained by a user sign-in failure. There is no session granted to the user's client since the sign-in failure.

Operations

List events

GET /api/v1/logs

Fetches a list of ordered log events from your Okta organization's system log

Request parameters

The following table summarizes the supported query parameters:

Parameter Description Format Default
since Filters the lower time bound of the log events published property for bounded queries or persistence time for polling queries The Internet Date/Time Format profile of ISO 8601 (opens new window), for example: 2017-05-03T16:22:18Z 7 days prior to until
until Filters the upper time bound of the log events published property for bounded queries or persistence time for polling queries The Internet Date/Time Format profile of ISO 8601 (opens new window), for example: 2017-05-03T16:22:18Z Current time
after Retrieves the next page of results. Okta returns a link in the HTTP Header (rel=next) that includes the after query parameter Opaque token
filter Filter Expression that filters the results SCIM Filter expression. All operators (opens new window) except [ ] are supported.
q Filters the log events results by one or more exact keywords URL encoded string. Max length is 40 characters per keyword, with a maximum of 10 keyword filters per query (before encoding)
sortOrder The order of the returned events that are sorted by published ASCENDING or DESCENDING ASCENDING
limit Sets the number of results that are returned in the response Integer between 0 and 1000 100
Request types

All requests to the /api/v1/logs endpoint fall into one of these two categories:

Polling requests

Polling requests are for situations when you want to consume an ongoing stream of events from Okta.

Example use cases include:

For a request to be a polling request, it must meet the following request parameter criteria:

  • until must be unspecified.
  • sortOrder must be ASCENDING.

Polling requests to the /api/v1/logs API have the following semantics:

  • They return every event that occurs in your organization.
  • The returned events are time filtered by their internal "persistence time" to avoid skipping records due to system delays (unlike Bounded Requests).
  • They may return events out of order according to the published field.
  • They have an infinite number of pages. That is, a next link relation header is always present, even if there are no new events (the event list may be empty).
Bounded requests

Bounded requests are for situations when you know the definite time period of logs you want to retrieve.

Example use cases include:

For a request to be a bounded request, it must meet the following request parameter criteria:

  • since must be specified.
  • until must be specified.

Bounded requests to the /api/v1/logs API have the following semantics:

  • The returned events are time filtered by their associated published field (unlike Polling Requests).
  • The returned events are guaranteed to be in order according to the published field.
  • They have a finite number of pages. That is, the last page doesn't contain a next link relation header.
  • Not all events for the specified time range may be present — events may be delayed. Such delays are rare but possible.
Filtering results
Expression filter

An expression filter is useful for performing structured queries where constraints on LogEvent attribute values can be explicitly targeted.

The following example expressions are supported for events with the filter query parameter:

Filter Description
eventType eq ":eventType" Events that have a specific action eventType
target.id eq ":id" Events that are published with a specific target ID
actor.id eq ":id" Events that are published with a specific actor ID

Note: SCIM filter expressions can't use the published attribute since it may conflict with the logic of the since, after, and until query params. In addition, a SCIM filter expression that uses the co (contains) operator with the debugContext.debugData.url or the debugContext.debugData.requestUri attribute is not supported. A request with an invalid SCIM filter expression returns an HTTP 400 API response.

See Filtering for more information on expressions.

The following are examples of filter expressions:

  • Events that are published for a target user
filter=target.id eq "00uxc78lMKUMVIHLTAXY"
  • Events that are published for all actors except for a specific user
filter=actor.id ne "00uxc78lMKUMVIHLTAXY"
  • Failed sign-in events
filter=eventType eq "user.session.start" and outcome.result eq "FAILURE"
  • Events that are published for a target user and application
filter=target.id eq "00uxc78lMKUMVIHLTAXY" and target.id eq "0oabe82gnXOFVCDUMVAK"
  • App SSO events for a target user and application
filter=eventType eq "app.auth.sso" and target.id eq "00uxc78lMKUMVIHLTAXY" and target.id eq "0oabe82gnXOFVCDUMVAK"
  • Events that are published for a given IP address
filter=client.ipAddress eq "184.73.186.14"
  • Events that start with event_hook
filter=eventType sw "event_hook"
  • Events that contain session
filter=eventType co "session"
  • Events that end with token
filter=eventType ew "token"
Keyword filter

The query parameter q can be used to perform keyword matching against a LogEvents object's attribute values. To satisfy the constraint, all supplied keywords must be matched exactly.

Note: Keyword matching is case-insensitive.

The following are examples of common keyword filtering:

  • Events that mention a specific city: q=San Francisco
  • Events that mention a specific URL: q=interestingURI.com
  • Events that mention a specific person: q=firstName lastName

Note: When hyphens are present in an event instance's attribute value, they are split and added to the list of matching candidates, in addition to the full hyphenated value. Therefore, events that contain the text XOxBw-2JIRnCFd0gG0GjHAAABjY are matched with a q value of XOxBw, 2JIRnCFd0gG0GjHAAABjY, or XOxBw-2JIRnCFd0gG0GjHAAABjY.

Datetime filter

LogEvent objects can be filtered by published attribute value with the following combination of parameters:

  • since
  • until
  • since and until
  • after

Note: since and after are mutually exclusive and can't be specified simultaneously.

The after parameter is system generated for use in "next" links. Don't attempt to craft requests that use this value. Rely on the system-generated links instead.

Response

The response contains a JSON array of LogEvent objects.

The response always includes a self link header, which is a link to the current query that was executed.

The header has the following format:

link: <url>; rel="self"

For example:

link: <https://{yourOktaDomain}/api/v1/logs?q=&sortOrder=DESCENDING&limit=20&until=2017-09-17T23%3A59%3A59%2B00%3A00&since=2017-06-10T00%3A00%3A00%2B00%3A00>; rel="self"

The response may include a next link header, which is a link to the next page of results, if there is one.

Note: While the self link always exists, the next link may not exist.

The header has the following format:

link: <url>; rel="next"

For example:

link: <https://{yourOktaDomain}/api/v1/logs?q=&sortOrder=DESCENDING&limit=20&until=2017-09-17T15%3A41%3A12.994Z&after=349996bd-5091-45dc-a39f-d357867a30d7&since=2017-06-10T00%3A00%3A00%2B00%3A00>; rel="next"

Timeouts

Individual queries have a timeout of 30 seconds.

Errors

{
  "errorCode": "E0000001",
  "errorSummary": "Api validation failed: 'until': The date format in your query is not recognized. Please enter dates using ISO8601 string format.. 'until': must be a valid date-time or empty.",
  "errorId": "dd4998a1-2267-499b-9e4d-ec821fcc5ca9",
  "errorCauses": [
    {
      "errorSummary": "until: The date format in your query is not recognized. Please enter dates using ISO8601 string format."
    },
    {
      "errorSummary": "until: must be a valid date-time or empty."
    }
  ]
}

An invalid SCIM filter returns the HTTP 400 error with a description of the issue with the SCIM filter, for example:

{
  "errorCode": "E0000053",
  "errorSummary": "Invalid filter 'display_message eqq \"Create okta user\"': Unrecognized attribute operator 'eqq' at position 16. Expected: eq,co,sw,pr,gt,ge,lt,le",
  "errorId": "eb83dfe1-6d76-458c-8c0c-f8df8fb7a24b"
}

An invalid field returns the HTTP 400 error with a message that indicates which field is invalid, for example:

{
  "errorCode": "E0000053",
  "errorSummary": "field is not valid: some_invalid_field",
  "errorId": "ec93dhe2-6d76-458c-8c0c-f8df8fb7a24b"
}

The following is another example, where the parameters are invalid:

{
  "errorCode": "E0000053",
  "errorSummary": "Invalid parameter: The since parameter is over 180 days prior to the current day.",
  "errorId": "55166534-b7d8-45a5-a4f6-3b38a5507046"
}

An invalid SCIM field and operator combination within a filter request parameter (for example, debugContext.debugData.url co "/oauth/") returns an HTTP 400 error with a message that indicates the unsupported combination, for example:

{
  "errorCode": "E0000031",
  "errorSummary": "The supplied combination of operator and field is not currently supported. Operator: co, Field: debugContext.debugData.url",
  "errorId": "ec93dhe2-6d76-458c-8c0c-f8df8fb7a24b"
}

An internal service error returns the HTTP 500 error with the message:

{
  "errorCode": "E0000053",
  "errorSummary": "Sorry, there's been an error. We aren't sure what caused it, but we've logged this and will work to address it. Please try your request again.",
  "errorId": "55166534-b7d8-45a5-a4f6-3b38a5507046"
}

A timeout returns the HTTP 500 error with the message:

{
  "errorCode": "E0000009",
  "errorSummary": "Your last request took too long to complete. This is likely due to a load issue on our side. We've logged this and will work to address it. Please either simplify your query or wait a few minutes and try again."
}

A free-form query that is too long returns the following error message:

{
  "errorCode": "E0000001",
  "errorSummary": "Api validation failed: 'q': Freeform search cannot contain items longer than 40 characters. Please shorten the items in your search or use an advanced filter to query by specific fields."
}

Exceeding the rate limit returns the following error message:

{
  "errorCode": "E0000047",
  "errorSummary": "API call exceeded rate limit due to too many requests."
}

Rate limits

See the tables entries for /api/v1/logs in Rate Limits.

Data retention

Log data older than 90 days isn't returned, in accordance with Okta's Data Retention Policy (opens new window). Queries that exceed the retention period succeed, but only those results that have a published timestamp within the window are returned.

Examples

Debugging

The System Log API can be used to troubleshoot user problems. For example, you can use the following curl command to see events from user "Jane Doe":

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/logs?q=Jane+Doe"

You can also use this API to search for particular types of events:

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/logs?filter=event_type+eq+%22user.session.start%22"

Transferring data to a separate system

You can export your log events to a separate system for analysis or compliance. To obtain the entire dataset, query from the appropriate point of time in the past.

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/logs?since=2017-10-01T00:00:00.000Z"

Then retrieve the next page of events through the link response header value with the next link relation. Continue this process until no events are returned.

Note: Don't transfer data by manually paginating using since and until, as this may lead to skipped or duplicated events. Instead, always follow the next links.