VerificationHistory

Represents the past six months of your org users’ attempts to verify their identity. This object is available in API version 36.0 and later.

Supported Calls

describeSObjects()query()retrieve()

Special Access Rules

Only users with “Manage Users” permission can access this object.

Fields

Field Name Details
Activity
Type
picklist
Properties
Filter, Group, Restricted picklist, Sort
Description
The action the user attempted that requires identity verification. The label is User Activity. Available values are:
  • AccessReports—The user attempted to access reports or dashboards.
  • Apex—The user attempted to access a Salesforce resource with a verification Apex method.
  • ChangeEmail—The user attempted to change an email address.
  • ConnectToopher—The user attempted to connect Salesforce Authenticator.
  • ConnectTotp—The user attempted to connect a one-time password generator.
  • ConnectU2F—The user attempted to register a U2F security key.
  • ConnectedApp—The user attempted to access a connected app.
  • EnableLL—The user attempted to enroll in Lightning Login.
  • ExportPrintReports—The user attempted to export or print reports or dashboards.
  • ExtraVerification—Reserved for future use.
  • Login—The user attempted to log in.
  • Registration—Reserved for future use.
  • TempCode—The user attempted to generate a temporary verification code.
EventGroup
Type
int
Properties
Filter, Group, Sort
Description
ID of the verification attempt. Verification can involve several attempts and use different verification methods. For example, in a user’s session, a user enters an invalid verification code (first attempt). The user then enters the correct code and successfully verifies identity (second attempt). Both attempts are part of a single verification and, therefore, have the same ID. The label is Verification Attempt.
LoginGeoId
Type
reference
Properties
Filter, Group, Nillable, Sort
Description
The 18-character ID for the record of the geographic location of the user for a successful or unsuccessful identity verification attempt. Due to the nature of geolocation technology, the accuracy of geolocation fields (for example, country, city, postal code) may vary.
LoginHistoryId
Type
reference
Properties
Filter, Group, Sort
Description
The ID for the record of the user’s successful or unsuccessful login attempt.
Policy
Type
picklist
Properties
Filter, Group, Restricted picklist, Sort
Description
The identity verification security policy or setting. The label is Triggered By. Available values are:
  • CustomApex—Identity verification made by a verification Apex method.
  • DeviceActivation—Identity verification required for users logging in from an unrecognized device or new IP address. This verification is part of Salesforce’s risk-based authentication.
  • EnableLightningLogin—Identity verification required for users enrolling in Lightning Login. This verification is triggered when the user attempts to enroll. Users are eligible to enroll if they have the “Lightning Login User” user permission and the org has enabled “Allow Lightning Login” in Session Settings.
  • ExtraVerification—Reserved for future use.
  • HighAssurance—High assurance session required for resource access. This verification is triggered when the user tries to access a resource, such as a connected app, report, or dashboard that requires a high-assurance session level.
  • LightningLogin—Identity verification required for internal users logging in via Lightning Login. This verification is triggered when the enrolled user attempts to log in. Users are eligible to log in if they have the “Lightning Login User” user permission, have successfully enrolled in Lightning Login, and the org has enabled “Allow Lightning Login” in Session Settings.
  • PageAccess—Identity verification required for users attempting to perform an action, such as changing an email address or adding a two-factor authentication method.
  • PasswordlessLogin—Identity verification required for external users attempting to log in to a community that is set up for passwordless login. The admin controls which registered verification methods can be used, for example, email, SMS, Salesforce Authenticator, or TOTP.
  • ProfilePolicy—Session security level required at login. This verification is triggered by the “Session security level required at login” setting on the user’s profile.
  • TwoFactorAuthentication—Two-factor authentication required at login. This verification is triggered by the “Two-Factor Authentication for User Interface Logins” user permission assigned to a custom profile. Or, the user permission is included in a permission set that is assigned to a user.
Remarks
Type
string
Properties
Filter, Group, Nillable, Sort
Description
The text the user sees on the screen or in Salesforce Authenticator when prompted to verify identity. For example, if identity verification is required for a user’s login, the user sees “You’re trying to Log In to Salesforce”. In this instance, the Remarks value is “Log In to Salesforce”. The exception is when the Activity value is Apex. In this instance, the Remarks value is a custom description passed by the Apex method. If the user is verifying identity using the Salesforce Authenticator app, the custom description displays in the app as well. If the custom description isn’t specified, the default value is the name of the Apex method. The label is Activity Message.
ResourceId
Type
reference
Properties
Filter, Group, Nillable, Sort
Description
If the Activity value is ConnectedApp, the ResourceId value is the ID of the connected app. The label is Connected App ID.
SourceIp
Type
string
Properties
Filter, Group, Sort
Description
The IP address of the machine from which the user attempted the action that requires identity verification. For example, the IP address of the machine from where the user tried to log in or access reports. If it’s a non-login action that required verification, the IP address can be different from the address from where the user logged in. This address can be an IPv4 or IPv6 address.
Status
Type
picklist
Properties
Filter, Group, Restricted picklist, Sort
Description
The status of the identity verification attempt. Available values are:
  • AutomatedSuccess—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.
  • Denied—The user denied the approval request in the authenticator app, such as Salesforce Authenticator.
  • FailedGeneralError—An error caused by something other than an invalid verification code, too many verification attempts, or authenticator app connectivity.
  • FailedInvalidCode—The user provided an invalid verification code.
  • FailedTooManyAttempts—The user attempted to verify identity too many times. For example, the user entered an invalid verification code repeatedly.
  • Initiated—Salesforce initiated identity verification but hasn’t yet challenged the user.
  • InProgress—Salesforce challenged the user to verify identity and is waiting for the user to respond or for Salesforce Authenticator to send an automated response.
  • RecoverableError—Salesforce can’t reach the authenticator app to verify identity, but will retry.
  • ReportedDenied—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.
  • Succeeded—The user’s identity was verified.
UserId
Type
reference
Properties
Filter, Group, Sort
Description
ID of the user verifying identity.
VerificationMethod
Type
picklist
Properties
Filter, Group, Nillable, Restricted picklist, Sort
Description
The method by which the user attempted to verify identity in the verification event. The label is Method. Available values are:
  • Email—Salesforce sent an email with a verification code to the address associated with the user’s account.
  • EnableLL—Salesforce Authenticator sent a notification to the user’s mobile device to enroll in Lightning Login. This value is available in API version 38.0 and later.
  • LL—Salesforce Authenticator sent a notification to the user’s mobile device to approve login via Lightning Login. This value is available in API version 38.0 and later.
  • SalesforceAuthenticator—Salesforce Authenticator sent a notification to the user’s mobile device to verify account activity.
  • Sms—Salesforce sent a text message with a verification code to the user’s mobile device.
  • TempCode—A Salesforce admin or a user with the “Manage Two-Factor Authentication in User Interface” permission generated a temporary verification code for the user. This value is available in API version 37.0 and later.
  • Totp—An authenticator app generated a time-based, one-time password (TOTP) on the user’s mobile device.
  • U2F—A U2F security key generated required credentials for the user. This value is available in API version 38.0 and later.
VerificationTime
Type
dateTime
Properties
Filter, Sort
Description
The time of the identity verification attempt. The time zone is based on GMT. The label is Time.

Usage

Here are two examples of the types of API queries you can perform.

Query String
Show verification history for a user’s login record SELECT Activity, EventGroup, Policy, Remarks, Status, UserId,VerificationMethod, VerificationTime FROM VerificationHistory WHERE LoginHistoryId = '0YaD000#########'
Get detailed geographic location information for a user’s verification attempt SELECT City, CountryIso, Latitude, Longitude, PostalCode FROM LoginGeo WHERE LoginGeoId = '0LE###############'