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#
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#
applicationId UUID optional The unique Id of the Application used to narrow the search results to logins for a particular application.
end Long optional The end instant of the date/time range to search within.
numberOfResults Integer optional Defaults to 25 The number of results to return from the search.
retrieveTotal Boolean optional Defaults 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.
start Long optional The start instant of the date/time range to search within.
startRow Integer optional Defaults to 0 The offset into the total results. In order to paginate the results, increment this value by the numberOfResults for subsequent requests.
userId String optional The unique Id of the User used to narrow the search results to login records for a particular user.
Using a request body#
OpenAPI Spec
When calling the API using a POST request you will send the search criteria in a JSON request body.
Request Body#
retrieveTotal Boolean optional Defaults 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.
search.applicationId UUID optional The unique Id of the Application used to narrow the search results to logins for a particular application.
search.end Long optional The end instant of the date/time range to search within.
search.numberOfResults Integer optional Defaults to 25 The number of results to return from the search.
search.start Long optional The start instant of the date/time range to search within.
search.startRow Integer optional Defaults to 0 The offset into the total results. In order to paginate the results, increment this value by the numberOfResults for subsequent requests.
search.userId UUID optional 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#
logins Array The list of Login Records returned by the search.
logins[x].applicationId UUID The unique Id of the application.
logins[x].applicationName String 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].loginId String 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].loginIdType String Available since 1.59.0The 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].instant Long The instant when the login occurred.
logins[x].ipAddress String The recorded IP address for this login record.
logins[x].userId UUID The unique Id of the user.
total Long 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
}