LoginEvent

Tracks user login events in your org. LoginEvent is evaluated in a transaction security policy. LoginEvent is a big object that stores the event data of LoginEventStream. This object is available in API version 36.0 and later.

Supported Calls

describeSObjects(), query()

Special Access Rules

Accessing this object requires the Shield Event Monitoring add-on, and the View Data Leakage Detection Events and API Enabled user permissions.

Fields

Field	Details
AdditionalInfo	Type string Properties Nillable Description JSON serialization of additional information that’s captured from the `HTTP` headers during a login request. For example, `{"field1": "value1","field2": "value2"}`. See Working with AdditionalInfo.
ApiType	Type string Properties Nillable Description English-only. The type of API that’s used to log in. Values include: `XML-RPC` `OSOAP` `SOAP Enterprise` `SOAP Partner` `SOAP Internal/CrossInstance` `REST API` `Metadata API` `N/A`
ApiVersion	Type string Properties Nillable Description English-only. The version number of the API. If no version number is available, “Unknown” is returned.
Application	Type string Properties Nillable Description The application name in English. For example, `Salesforce Internal Application` or `Microsoft SOAP Toolkit`.
AuthServiceId	Type reference Properties Nillable Description Refers to the AuthenticationServiceId field in the LoginHistory object. For example, you can use this field to identify the SAML or authentication provider configuration with which the user logged in.
Browser	Type string Properties Nillable Description The browser name and version if known. If no browser or version number is available, “Unknown” is returned. Product names are in English.
CipherSuite	Type picklist Properties Nillable, Restricted picklist Description The TLS cipher suite used for the login. Values are OpenSSL-style cipher suite names, with hyphen delimiters, for example, `AES128-GCM-SHA256`. Available in API version 37.0 and later. Valid values are: `AES128-GCM-SHA256` `AES128-SHA` `AES128-SHA256` `AES256-GCM-SHA384` `AES256-SHA` `AES256-SHA256` `DES-CBC3-SHA` `DHE-RSA-AES128-GCM-SHA256` `DHE-RSA-AES128-SHA` `DHE-RSA-AES256-GCM-SHA384` `DHE-RSA-AES256-SHA` `DHE-RSA-DES-CBC3-SHA` `ECDH-ECDSA-AES128-GCM-SHA256` `ECDH-ECDSA-AES128-SHA256` `ECDH-ECDSA-AES256-GCM-SHA384` `ECDH-ECDSA-AES256-SHA384` `ECDH-RSA-AES128-GCM-SHA256` `ECDH-RSA-AES128-SHA256` `ECDH-RSA-AES256-GCM-SHA384` `ECDH-RSA-AES256-SHA384` `ECDHE-ECDSA-AES128-GCM-SHA256` `ECDHE-ECDSA-AES128-SHA256` `ECDHE-ECDSA-AES256-GCM-SHA384` `ECDHE-ECDSA-AES256-SHA384` `ECDHE-RSA-AES128-CBC-SHA` `ECDHE-RSA-AES128-GCM-SHA256` `ECDHE-RSA-AES128-SHA` `ECDHE-RSA-AES128-SHA256` `ECDHE-RSA-AES256-CBC-SHA` `ECDHE-RSA-AES256-GCM-SHA384` `ECDHE-RSA-AES256-SHA` `ECDHE-RSA-AES256-SHA384` `ECDHE-RSA-DES-CBC3-SHA` `Unknown`
ClientVersion	Type string Properties Nillable Description English-only. The version number of the login client. If no version number is available, “Unknown” is returned.
CountryIso	Type string Properties Nillable Description The ISO 3166 code for the country where the user’s IP address is physically located. For more information, see Country Codes - ISO 3166. This field is available in API version 37.0 and later.
EvaluationTime	Type double Properties Nillable, Description The amount of time it took to evaluate the transaction security policy, in milliseconds. This field is available only in the Real-Time Events pilot in API version 42.0 and later.
EventDate	Type dateTime Properties Filter, Sort Description The login time of the specified event. For example, `2013-01-01T03:01:01Z`. Seconds are the most granular setting.
EventIdentifier	Type string Properties Filter, Sort Description The unique identifier for each record in LoginEvent. Available in API version 42.0 and later. Use this field as the primary key in your queries instead of the UniqueKey field (deprecated in API version 42.0) or the Id system field (not populated in API version 40.0 and later).
HttpMethod	Type picklist Properties Nillable, Restricted picklist Description The HTTP method of the login request; possible values are `GET`, `POST`, and `Unknown`.
LoginGeoId	Type reference Properties Nillable Description The Salesforce ID of the LoginGeo object associated with the login user’s IP address.
LoginHistoryId	Type reference Properties Nillable Description Tracks a user session so you can correlate user activity with a particular login instance.
LoginKey	Type string Properties Nillable Description The string that ties together all events in a given user’s login session. The session starts with a login event and ends with either a logout event or the user session expiring. This field is available only in the Real-Time Events pilot in API version 42.0 and later.
LoginType	Type picklist Properties Nillable, Restricted picklist Description
LoginUrl	Type string Properties Nillable Description The URL of the login host. For example, `yourInstance.salesforce.com`.
NetworkId	Type reference Properties Filter, Group, Nillable, Sort Description The ID of the community that the user is logging in to. This field is available if Salesforce Communities is enabled for your organization.
Platform	Type string Properties Nillable Description The platform name and version that are used during the login event. If no platform name is available, “Unknown” is returned. Platform names are in English.
PolicyId	Type reference Properties Nillable Description The ID of the transaction security policy associated with this event. This field is available only in the Real-Time Events pilot in API version 42.0 and later.
PolicyOutcome	Type picklist Properties Nillable, Restricted picklist Description The result of the transaction policy. Possible values are: `Block`—The user was blocked from performing the operation that triggered the policy. `EndSession`—The Concurrent Sessions Limiting policy activated, limiting the number of concurrent sessions per user. `Error`—The policy caused an undefined error when it executed. `FailedInvalidPassword`—The user entered an invalid password. `FailedPasswordLockout`—The user entered an invalid password too many times. `NoAction`—The policy didn't trigger. `Notified`—A notification was sent to the recipient. `TwoFAAutomatedSuccess`—Salesforce Authenticator approved the request for access because the request came from a trusted location. After users enable location services in Salesforce Authenticator, they can designate trusted locations. When a user trusts a location for a particular activity, such as logging in from a recognized device, that activity is approved from the trusted location for as long as the location is trusted. `TwoFADenied`—The user denied the approval request in the authenticator app, such as Salesforce Authenticator. `TwoFAFailedGeneralError`—An error caused by something other than an invalid verification code, too many verification attempts, or authenticator app connectivity. `TwoFAFailedInvalidCode`—The user provided an invalid verification code. `TwoFAFailedTooManyAttempts`—The user attempted to verify identity too many times. For example, the user entered an invalid verification code repeatedly. `TwoFAInitiated`—Salesforce initiated identity verification but hasn’t yet challenged the user. `TwoFAInProgress`—Salesforce challenged the user to verify identity and is waiting for the user to respond or for Salesforce Authenticator to send an automated response. `TwoFANoAction`—The policy specifies two factor authentication as an action, but the user is already in a high-assurance session. `TwoFARecoverableError`—Salesforce can’t reach the authenticator app to verify identity, but will retry. `TwoFAReportedDenied`—The user denied the approval request in the authenticator app, such as Salesforce Authenticator, and also flagged the approval request to report to an administrator. `TwoFASucceeded`—The user’s identity was verified. This field is available only in the Real-Time Events pilot in API version 42.0 and later.
RelatedEventIdentifier	Type string Properties Nillable Description Represents the EventIdentifier of the related event.
SessionKey	Type string Properties Nillable Description The user’s unique session ID. Use this value to identify all user events within a session. When a user logs out and logs in again, a new session is started. For LoginEvent, this field is usually null because the event is captured before a session is created. This field is available only in the Real-Time Events pilot in API version 42.0 and later.
SessionLevel	Type picklist Properties Nillable, Restricted picklist Description Session-level security controls user access to features that support it, such as connected apps and reporting. Possible values are: `HIGH_ASSURANCE`—A high assurance session was used for resource access. For example, when the user tries to access a resource such as a connected app, report, or dashboard that requires a high-assurance session level. `LOW`—The user’s security level for the current session meets the lowest requirements. This low level is not available, nor used, in the Salesforce UI. User sessions through the UI are either standard or high assurance. You can set this level using the API, but users assigned this level will experience unpredictable and reduced functionality in their Salesforce org. Note `STANDARD`—The user’s security level for the current session meets the Standard requirements set in the org’s Session Security Levels. This field is available in API version 42.0 and later.
SourceIp	Type string Properties Nillable Description The source IP address of the client logging in. For example, `126.7.4.2`.
Status	Type string Properties Nillable Description The login status is in English. "Success" is returned when successful. Otherwise, an error message is returned.
TlsProtocol	Type picklist Properties Nillable, Restricted picklist Description The TLS protocol version used for the login. Available in API version 37.0 and later. Valid values are: `TLS 1.0` `TLS 1.1` `TLS 1.2` `Unknown`
UserId	Type reference Properties Nillable Description The user’s unique ID. For example, `005000000000123`.
Username	Type string Properties Nillable Description The username in the format of `user@company.com`.
UserType	Type picklist Properties Nillable, Restricted picklist Description The category of user license. Each UserType is associated with one or more UserLicense records. Each UserLicense is associated with one or more profiles. Valid values are: `CsnOnly`—Users whose access to the application is limited to Chatter. This user type includes Chatter Free and Chatter moderator users. `CspLitePortal`—CSP Lite Portal license. Users whose access is limited because they are organization customers and access the application through a customer portal or community. `CustomerSuccess`—Customer Success license. Users whose access is limited because they are organization customers and access the application through a customer portal. `Guest` This field is available only in the Real-Time Event Monitoring (Beta) in API version 42.0 and later.

Working with AdditionalInfo

AdditionalInfo enables you to extend the login event with custom data that can be queried later. For example, you can capture a correlation ID when a user logs in from an external system that shares that unique ID. This process enables tracking logins across systems. To store data with LoginEvent, begin all AdditionalInfo field names with x-sfdc-addinfo-{fieldname}. For example, a valid field assignment is x-sfdc-addinfo-correlation_id = ABC123 where x-sfdc-addinfo-correlation_id is the field name and ABC123 is the field value.

When defining field names, note the following:

x-sfdc-addinfo- is case-insensitive. x-sfdc-addinfo-{field name} is the same as X-SFDC-ADDINFO-{FIELD NAME}.
Fields can contain only alphanumeric and “_” (underscore) characters.
Field names must be between 2 and 29 characters in length, excluding x-sfdc-addinfo-.
Field names that don’t start with x-sfdc-addinfo- are ignored.
Names that contain invalid characters after x-sfdc-addinfo- are ignored.
Only the first 30 valid field names are stored in AdditionalInfo. Field names are not necessarily stored in the same order in which they were passed to authentication.

When determining field values, keep the following in mind:

You can’t use existing API field names as AdditionalInfo names in the HTTP header. If the AdditionalInfo name conflicts with an object’s API name, the field value isn’t stored. For example, the HTTP header X-SFDC-ADDINFO-UserId='abc123' doesn’t get stored in AdditionalInfo.
Additional field values can contain only alphanumeric, “_,” and “-” characters.
Field values must be 255 characters in length or fewer. If a field value exceeds 255 characters, only the first 255 characters are stored and the rest are truncated.
Field values that contain invalid characters are saved with a field header of Empty String ("").
Only the first 30 valid field names are stored in the AdditionalInfo field. They are not guaranteed to be stored in the same order that they were passed into the authentication.
When AggregationFieldName is SourceIp, you can’t filter on AggregationFieldValue if its value is Salesforce.com IP.

How to Pass Additional Information by Using HTTP with cURL

Here’s an example of passing additional information via the command line.

How to Pass Additional Information in Java

Here’s an example of passing additional information in Java.

Standard SOQL Usage

Currently, the only supported SOQL function on LoginEvent is WHERE, and you can only use comparison operators (=, <, >, <=, and >=) on the final expression in a WHERE clause. The != operator isn’t supported.

Date functions such as convertTimezone() aren’t supported. For example, SELECT CALENDAR_YEAR(EventDate), Count(EventIdentifier) FROM LoginEvent GROUP BY CALENDAR_YEAR(EventDate) returns an error. You can use date literals in your queries and some date and date/time functions like TODAY, YESTERDAY, and LAST_n_DAYS:1. However, these functions use comparison operators behind the scenes. This means you can only use them in the final expression of a WHERE clause.

Note

LoginEvent allows filtering over two ordered fields: EventDate and EventIdentifier. There’s a catch here; your query won’t work unless you use the correct order and combination of these fields. The following list provides some examples of valid and invalid queries:

Unfiltered
- Valid—Contains no WHERE clause, so no special rules apply.
Filtered on EventDate
- Valid—You can filter solely on EventDate, but single filters on other fields fail. You can also use a comparison operator in this query type.
- Valid—You can filter on EventDate using date literals.
Filtered on EventDate and EventIdentifier
- Valid—Successful queries on LoginEvent filter over both fields.
- Invalid—Queries on LoginEvent with EventDate and standard date literals.
- Invalid—Filtering only on EventDate with <= or >= operator and EventIdentifier field isn’t supported.

Async SOQL Usage

With Async SOQL, you can filter on any field in LoginEvent and use any comparison operator in your query.

Example: Get Yesterday’s Successful Logins

SELECT Application, Browser, EventDate, EventIdentifier, LoginUrl, UserId FROM LoginEvent WHERE EventDate<Yesterday AND Status=’Success’

Platform Events Developer Guide