LoginEvent tracks the login activity of users who log in to Salesforce. You can use LoginEvent 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 either the Salesforce Shield or Salesforce Event Monitoring add-on subscription and the View Real-Time Event Monitoring Data user permission.
LoginEvent doesn’t track login activity after login rates exceed the limit. This condition applies to all users, including integration users and internal users who log in to Salesforce.
Description: JSON serialization of additional information that’s captured from the HTTP headers during a login request. For example, {"field1": "value1","field2": "value2"}.
ApiType
Type: string
Properties: Nillable
Description: The type of API that’s used to log in. Values include SOAP Enterprise, SOAP Partner, or REST API.
ApiVersion
Type: string
Properties: Nillable
Description: The version number of the API. If no version number is available, “Unknown” is returned.
Application
Type: string
Properties: Nillable
Description: The application used to access the org. Possible values include AppExchange, Browser, Salesforce for iOS, Salesforce Developers API Explorer, or N/A.
AuthContextClassRef
Type: string
Properties: Filter, Group, Nillable, Sort
Description: If provided by a third-party identity provider, the authentication method indicated in the Authentication Context Class Reference (ACR) claim. SAML providers store the value of the AuthnContextClassRef statement in the SAML response. OpenID Connect providers store the value of the ACR claim in the ID token. This field is available in API version 67.0 and later.
AuthMethodReference
Type: string
Properties: Nillable
Description: The authentication method used by a third-party identification provider for an OpenID Connect single sign-on protocol. This field is available in API version 51.0 and later.
AuthServiceId
Type: reference
Properties: Nillable
Description: The 18-character ID for an authentication service for a login event. 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. Possible values for the browser name are Chrome, Firefox, Safari, or Unknown. For example, “Chrome 77”.
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, ECDHE-RSA-AES256-GCM-SHA384. Available in API version 37.0 and later.
City
Type: string
Properties: Nillable
Description: The city where the user’s IP address is physically located. This value isn’t localized. This field is available in API version 47.0 and later.
ClientVersion
Type: string
Properties: Nillable
Description: The version number of the login client. If no version number is available, “Unknown” is returned.
Country
Type: string
Properties: Nillable
Description: The country where the user’s IP address is physically located. This value isn’t localized. This field is available in API version 47.0 and later.
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 in API version 46.0 and later.
EventDate
Type: dateTime
Properties: Filter, Sort
Description: The login time of the specified event. For example, 2020-01-20T19:12:26.965Z. Milliseconds are the most granular setting.
EventIdentifier
Type: string
Properties: Filter, Sort
Description: The unique identifier for each record in LoginEvent. Use this field as the primary key in your queries. Available in API version 42.0 and later.
ForwardedForIp
Type: string
Properties: Filter, Group, Nillable, Sort
Description: The value in the X-Forwarded-For header of HTTP requests sent by the client. For logins that use one or more HTTP proxies, the X-Forwarded-For header is sometimes used to store the origin IP and all proxy IPs. The ForwardedForIp field stores whatever value the client sends, which might not be an IP address. The maximum length is 256 characters. Longer values are truncated. The ForwardedForIp field isn’t populated for logins completed via OAuth flows or single sign-on (SSO). Available in API version 61.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. For example, 04FB000001TvhiPMAR.
LoginHistoryId
Type: reference
Properties: Nillable
Description: Tracks a user session so you can correlate user activity with a particular login instance. This field is also available on the LoginHistory, AuthSession, and other objects, making it easier to trace events back to a user’s original authentication. For example, 0YaB000002knVQLKA2.
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 in API version 46.0 and later. For example, lUqjLPQTWRdvRG4.
LoginLatitude
Type: double
Properties: Nillable
Description: The latitude where the user’s IP address is physically located. This field is available in API version 47.0 and later.
LoginLongitude
Type: double
Properties: Nillable
Description: The longitude where the user’s IP address is physically located. This field is available in API version 47.0 and later.
LoginSubType
Type: picklist
Properties: Nillable, Restricted picklist,
Description: The type of login flow used. See the LoginSubType field of LoginHistory in the Object Reference guide for the list of possible values. Label is Login Subtype.
LoginType
Type: picklist
Properties: Nillable, Restricted picklist
Description: The type of login used to access the session. See the LoginType field of LoginHistory in the Object Reference guide for the list of possible values.
LoginUrl
Type: string
Properties: Nillable
Description: The URL of the login host from which the request is coming. For example, yourInstance.salesforce.com.
Platform
Type: string
Properties: Nillable
Description: The operating system name and version that are used during the login event. If no platform name is available, “Unknown” is returned. For example, Mac OSX or iOS/Mac.
PolicyId
Type: reference
Properties: Nillable
Description: The ID of the transaction security policy associated with this event. This field is available in API version 46.0 and later. For example, 0NIB000000000KOOAY.
PolicyOutcome
Type: picklist
Properties: Nillable, Restricted picklist
Description: The result of the transaction policy. This field is available in API version 46.0 and later.
Possible values:
Block—The user was blocked from performing the operation that triggered the policy.
Error—The policy caused an undefined error when it executed.
ExemptNoAction—The user is exempt from transaction security policies, so the policy didn’t trigger.
FailedInvalidPassword—The user entered an invalid password.
FailedPasswordLockout—The user entered an invalid password too many times.
MeteringBlock—The policy took longer than 3 seconds to process, so the user was blocked from performing the operation.
MeteringNoAction—The policy took longer than 3 seconds to process, but the user isn’t blocked from performing the operation.
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, that activity is approved from the trusted location for as long as the location is trusted. An example of a particular activity is logging in from a recognized device.
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 multi-factor authentication (formerly called 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.
PostalCode
Type: string
Properties: Nillable
Description: The postal code where the user’s IP address is physically located. This value isn’t localized. This field is available in API version 47.0 and later.
ProfileId
Type: reference
Properties: Nillable
Description: This is a relationship field.
Relationship Name: Profile
Refers To: Profile
RelatedEventIdentifier
Type: string
Properties: Nillable
Description: Represents the EventIdentifier of the related event. For example, bd76f3e7-9ee5-4400-9e7f-54de57ecd79c. This field is populated only when the activity that this event monitors requires extra authentication, such as multi-factor authentication. In this case, Salesforce generates more events and sets the RelatedEventIdentifier field of the new events to the value of the EventIdentifier field of the original event. Use this field with the EventIdentifier field to correlate all the related events. If no extra authentication is required, this field is blank.
RoleId
Type: reference
Properties: Nillable
Description: This is a relationship field.
Relationship Name: Role
Refers To: UserRole
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 often null because the event is captured before a session is created. For example, vMASKIU6AxEr+Op5. This field is available in API version 46.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. This field is available in API version 42.0 and later.
Possible values:
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.
STANDARD—The user’s security level for the current session meets the Standard requirements set in the org’s Session Security Levels.
Note: The LOW session level isn’t 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 experience unpredictable and reduced functionality in their Salesforce org.
SourceIp
Type: string
Properties: Nillable
Description: The IP address of the incoming client request that first reaches Salesforce during a login. For example, 126.7.4.2. For clients that redirect through one or more HTTP proxies, this field stores the IP address of the first proxy to reach Salesforce. To better identify the origin IP for these cases, check the ForwardedForIp field instead.
Status
Type: string
Properties: Nillable
Description: Displays the status of the attempted login. Status is either success or a reason for failure.
Subdivision
Type: string
Properties: Nillable
Description: The name of the subdivision where the user’s IP address is physically located. In the U.S., this value is usually the state name (for example, Pennsylvania). This value isn’t localized. This field is available in API version 47.0 and later.
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, TLS 1.3, or 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. This field is available only in the Real-Time Event Monitoring in API version 42.0 and later.
Valid values:
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’re organization customers and access the application through a customer portal or Experience Cloud site.
CustomerSuccess—Customer Success license. Users whose access is limited because they’re organization customers and access the application through a customer portal.
Guest
PowerCustomerSuccess—Power Customer Success license. Users whose access is limited because they’re organization customers and access the application through a customer portal. Users with this license type can view and edit data they directly own or data owned by or shared with users below them in the customer portal role hierarchy.
PowerPartner—Power Partner license. Users whose access is limited because they’re partners and typically access the application through a partner portal or site.
SelfService
Standard—Standard user license. This user type also includes Salesforce Platform and Salesforce Platform One user licenses.
Note: Due to the nature of geolocation technology, the accuracy of City, Country, LoginLatitude, LoginLongitude, PostalCode, and Subdivision can vary.
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 from 2 and 29 characters in length, excluding x-sfdc-addinfo-.
Field names that don’t start with x-sfdc-addinfo- are ignored.
Field names that contain invalid characters after x-sfdc-addinfo- can cause an HTTP 400 Bad Request error.
Only the first 30 valid field names are stored in AdditionalInfo. Field names aren’t 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 aren’t 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.
Here’s an example of passing additional information in Java.
1//adding additional info headers ..2Map<String, String>httpHeaders = new HashMap<String,String>();3httpHeaders.put("x-sfdc-addinfo-fieldname1" /* additional info field*/ ,4"d18c5a3f-4fba-47bd-bbf8-6bb9a1786624" /* value*/);5httpHeaders.put("x-sfdc-addinfo-fieldname2" /* additional info field*/ ,6"d18c5a3f-4fba-47bd-bbf8-6bb9a1786624" /* value*/);7ConnectorConfig config = new ConnectorConfig();8config.setUsername(userId);9config.setPassword(passwd);10config.setAuthEndpoint(authEndPoint);11config.setProxy(proxyHost, proxyPort);12//setting additional info headers13for(Map.Entry<String, String>entry : httpHeaders.entrySet()){14config.setRequestHeader(entry.getKey(), entry.getValue());15}16// Set the username and password if your proxy must be authenticated17918LoginEvent19config.setProxyUsername(proxyUsername);20config.setProxyPassword(proxyPassword);21try{22EnterpriseConnection connection = new EnterpriseConnection(config);23// etc.24}catch(ConnectionException ce){25ce.printStackTrace();26}
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, which 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. Your query doesn’t work unless you use the correct order and combination of these fields. These examples show valid and invalid queries.
Unfiltered
Valid: Contains no WHERE clause, so no special rules apply.
j