Search Login Records

Available Since Version 1.7.0

This API allows you to search and paginate through the Login Records. Login Records are created in the following scenarios:

A login is completed using any Login API (normal, one-time, passwordless, Identity Provider, Connector).
A User is created with a password, whether self service or using the Registration API.
A Refresh Token is exchanged for a JWT.
A 2FA login is completed.

You can limit the number of Login Records retained by navigating to Settings -> System -> Advanced -> Login record settings and configuring automatic deletion of Login Records after a certain number of days.

Request#

Using GET parameters#

Searches for Login Records given search criteria

When calling the API using a GET request you will send the search criteria on the URL using request parameters. In order to simplify the example URL above, not every possible parameter is shown, however using the provided pattern you may add any of the documented request parameters to the URL.

Request Parameters#

applicationIdUUIDoptional

The unique Id of the Application used to narrow the search results to logins for a particular application.

endLongoptional

The end instant of the date/time range to search within.

numberOfResultsIntegeroptionalDefaults to 25

The number of results to return from the search.

retrieveTotalBooleanoptionalDefaults to false

Set this to true if you want the total possible results returned in the response. With a very large number of login records settings this value to true will increase the response time of this request.

startLongoptional

The start instant of the date/time range to search within.

startRowIntegeroptionalDefaults to 0

The offset into the total results. In order to paginate the results, increment this value by the numberOfResults for subsequent requests.

userIdStringoptional

The unique Id of the User used to narrow the search results to login records for a particular user.

Using a request body#

Searches for Login Records given search criteria

OpenAPI Spec

When calling the API using a POST request you will send the search criteria in a JSON request body.

Request Body#

retrieveTotalBooleanoptionalDefaults to false

search.applicationIdUUIDoptional

The unique Id of the Application used to narrow the search results to logins for a particular application.

search.endLongoptional

The end instant of the date/time range to search within.

search.numberOfResultsIntegeroptionalDefaults to 25

The number of results to return from the search.

search.startLongoptional

The start instant of the date/time range to search within.

search.startRowIntegeroptionalDefaults to 0

The offset into the total results. In order to paginate the results, increment this value by the numberOfResults for subsequent requests.

search.userIdUUIDoptional

The unique Id of the User used to narrow the search results to login records for a particular user.

Response#

The response for this API will contain all login records matching the search criteria in paginated format.

Response Codes

Code	Description
200	The request was successful. The response will contain a JSON body.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present.
401	You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
404	The object you requested doesn't exist. The response will be empty.
500	There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.
503	The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

Response Body#

loginsArray

The list of Login Records returned by the search.

logins[x].applicationIdUUID

The unique Id of the application.

logins[x].applicationNameString

The name of the application. Because the application name may be modified after the login event occurred, only the applicationId should be considered immutable for historical purposes when identifying the application.

logins[x].loginIdString

The identity used to log in. Because an identity may be modified after the login event occurred, only the userId should be considered immutable for historical purposes when identifying the user.

In version 1.59.0 and later, the loginId is stored in the login record when the correct value can be identified. In these cases the loginIdType will be populated.

logins[x].loginIdTypeStringAvailable since 1.59.0

The type of identity used to log in. A missing value on the response indicates the login was not associated with a specific identity, or the login record was created prior to version 1.59.0.

logins[x].instantLong

The instant when the login occurred.

logins[x].ipAddressString

The recorded IP address for this login record.

logins[x].userIdUUID

The unique Id of the user.

totalLong

The total number of login records available. This will only be provided in the response when retrieveTotal was set to true on the request.

Example JSON Response

{
  "logins": [
    {
      "applicationId": "2edd54c6-695d-409e-b8af-2d3ebf73711a",
      "applicationName": "Pied Piper Admin Portal",
      "loginId": "richard@piedpiper.com",
      "instant": 1562608320303,
      "ipAddress": "42.42.42.42",
      "userId": "d7be5e1e-0020-4f6f-a9dc-0f9230650042"
    },
    {
      "applicationId": "3c219e58-ed0e-4b18-ad48-f4f92793ae32",
      "applicationName": "FusionAuth",
      "loginId": "monica@piedpiper.com",
      "loginIdType": "email",
      "instant": 1562608320901,
      "ipAddress": "192.168.1.1",
      "userId": "af8fb4d8-df6b-41c6-9843-813da943b005"
    },
    {
      "applicationId": "2edd54c6-695d-409e-b8af-2d3ebf73711a",
      "applicationName": "Pied Piper Admin Portal",
      "loginId": "richard@piedpiper.com",
      "instant": 1562608399639,
      "ipAddress": "42.42.42.42",
      "userId": "d7be5e1e-0020-4f6f-a9dc-0f9230650042"
    }
  ],
  "total": 3
}