> ## Documentation Index > Fetch the complete documentation index at: https://docs.guardhousehq.com/llms.txt > Use this file to discover all available pages before exploring further. # List login audit events > Returns login audit events for the caller's company, newest first. > **Special-scope key required.** This endpoint is gated by the `login-audits.read` entitlement. Your API key must be issued with that scope or the request will be rejected with `403 Forbidden`. Contact Guardhouse Support to have the scope added to an existing key. **Tenant scope:** the company is taken from your access token's `CompanyId` claim. Passing `companyId` in the query string is ignored — cross-tenant isolation is enforced server-side. Results are ordered by `occurredUtc` descending and paged with `Skip((page - 1) * pageSize).Take(pageSize)`. There is no `totalCount` field — when fewer than `pageSize` rows are returned, you have reached the end. ## OpenAPI ````yaml /api-reference/openapi.json get /api/external/loginaudit openapi: 3.1.0 info: title: Guardhouse API version: 1.0.0 description: >- The Guardhouse API gives external systems programmatic access to incident reports, timesheets, staff, customers, sites, and webhook event subscriptions. All endpoints return a consistent envelope (`ApiResponse`, `ApiPagedResponse`, or `ApiPostPagedResponse`). Authentication is a two-step flow: exchange a long-lived **API key** for a short-lived **JWT bearer token**, then send the bearer on every subsequent request. contact: name: Guardhouse Support license: name: Proprietary servers: - url: https://gateway-api.guardhousehq.com description: AU production - url: https://gateway-api.guardhousehq.co.uk description: UK production security: - bearerAuth: [] subscriptionKey: [] tags: - name: Authentication description: >- Exchange a long-lived API key for a short-lived JWT bearer token. The token must be sent as `Authorization: Bearer ` on every subsequent request. - name: Incident Reports description: >- List, fetch, and export incident reports submitted against your customers and sites. Requires an API key with `KeyType=incidentreport`. - name: Timesheets description: List timesheet entries and fetch per-entry rate breakdowns. - name: Live Operations description: >- Retrieve live shift and employee operational data, including clock-in status, location, welfare checks, and license details. - name: Staff description: >- List, create, and update employees and their security licenses. Read endpoints (`GET /api/external/staffs`, `GET /api/external/staffs/{id}/licenses`) are accessible with any valid Public API key. Write endpoints (`POST`, `PATCH`, `GET /staffs/search`) require `KeyType=developer`. - name: Customers description: List customer records visible to your API key. - name: Sites description: List sites visible to your API key. - name: Webhooks description: >- Manage webhook subscribers and event subscriptions so Guardhouse can notify your systems when incident reports or timesheets change. Requires an API key with `KeyType=developer`. - name: Login Audit description: >- Read-only access to login activity (successful logins, failed logins, and reserved logout events) for your company. **Requires an API key issued with the `login-audits.read` entitlement scope** — keys without this special scope are rejected at the auth layer with `403 Forbidden`. Tokens minted from such a key carry `login-audits.read` in their `Scope` claim, which is what the endpoint checks. paths: /api/external/loginaudit: get: tags: - Login Audit summary: List login audit events description: >- Returns login audit events for the caller's company, newest first. > **Special-scope key required.** This endpoint is gated by the `login-audits.read` entitlement. Your API key must be issued with that scope or the request will be rejected with `403 Forbidden`. Contact Guardhouse Support to have the scope added to an existing key. **Tenant scope:** the company is taken from your access token's `CompanyId` claim. Passing `companyId` in the query string is ignored — cross-tenant isolation is enforced server-side. Results are ordered by `occurredUtc` descending and paged with `Skip((page - 1) * pageSize).Take(pageSize)`. There is no `totalCount` field — when fewer than `pageSize` rows are returned, you have reached the end. parameters: - name: userId in: query description: Filter to a specific user. schema: type: integer format: int32 - name: eventType in: query description: >- Filter by event type. `1` = LoginSuccess, `2` = LoginFailure, `3` = Logout (reserved). schema: type: integer format: int32 enum: - 1 - 2 - 3 - name: from in: query description: >- Inclusive lower bound on `occurredUtc` (ISO-8601 UTC, e.g. `2026-04-01T00:00:00Z`). schema: type: string format: date-time - name: to in: query description: Inclusive upper bound on `occurredUtc` (ISO-8601 UTC). schema: type: string format: date-time - name: page in: query description: 1-based page index. Must be `>= 1`. schema: type: integer format: int32 default: 1 minimum: 1 - name: pageSize in: query description: Page size. Must be between `1` and `500`. schema: type: integer format: int32 default: 50 minimum: 1 maximum: 500 responses: '200': description: Paged list of login audit events. content: application/json: schema: $ref: '#/components/schemas/LoginAuditListEnvelope' '400': $ref: '#/components/responses/ValidationError' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/ScopeForbidden' components: schemas: LoginAuditListEnvelope: allOf: - $ref: '#/components/schemas/LoginAuditEnvelope' - type: object properties: data: type: array nullable: true items: $ref: '#/components/schemas/LoginAudit' LoginAuditEnvelope: type: object description: >- Standard `{ data, errors, meta }` envelope used by Login Audit endpoints. Differs from the legacy `ApiResponse` envelope used by older endpoints. properties: data: nullable: true description: Endpoint-specific payload. `null` when `errors` is populated. errors: type: array nullable: true items: $ref: '#/components/schemas/LoginAuditEnvelopeError' meta: $ref: '#/components/schemas/LoginAuditEnvelopeMeta' LoginAudit: type: object description: >- A single login audit row. Written on every successful and failed login via `POST /api/token/requesttoken` (password) and `POST /api/external/token/request` (API key). Refresh-token calls are not audited. properties: id: type: integer format: int64 description: Audit row primary key. userId: type: integer format: int32 nullable: true description: '`null` for unauthenticated failures (e.g. unknown email).' companyId: type: integer format: int32 nullable: true description: >- Always equals the caller's `CompanyId` for rows visible to this endpoint. eventType: type: integer format: int32 enum: - 1 - 2 - 3 description: >- `1` = LoginSuccess, `2` = LoginFailure, `3` = Logout (reserved — not yet emitted). authMethod: type: integer format: int32 enum: - 1 - 2 description: '`1` = Password, `2` = ApiKey.' appType: type: string nullable: true maxLength: 50 description: Originating app, e.g. `Internal`, `External`. emailAttempted: type: string nullable: true maxLength: 256 description: >- The email submitted at login. Redacted to `null` when `userId` is `null` on this external endpoint. ipAddress: type: string nullable: true maxLength: 45 description: >- First hop of `X-Forwarded-For` if present, else the remote IP. IPv4 or IPv6. userAgent: type: string nullable: true maxLength: 512 description: Truncated to 512 chars. failureReason: type: string nullable: true maxLength: 100 description: >- Set on `LoginFailure` events (e.g. `InvalidCredentials`). `null` on success. occurredUtc: type: string format: date-time description: When the event happened. Always UTC. LoginAuditEnvelopeError: type: object properties: code: type: string message: type: string field: type: string nullable: true LoginAuditEnvelopeMeta: type: object properties: traceId: type: string description: Server-side trace identifier — include in support requests. timestampUtc: type: string format: date-time nextPageEndpoint: type: string nullable: true prevPageEndpoint: type: string nullable: true responses: ValidationError: description: >- One or more query parameters failed validation (e.g. `page < 1`, `pageSize` outside `[1, 500]`). content: application/json: schema: $ref: '#/components/schemas/LoginAuditEnvelope' Unauthorized: description: The bearer token is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/LoginAuditEnvelope' ScopeForbidden: description: >- The bearer token is valid but the issuing API key was not provisioned with the special `login-audits.read` entitlement scope. Request the scope from Guardhouse Support and re-issue the key. content: application/json: schema: $ref: '#/components/schemas/LoginAuditEnvelope' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- JWT issued by `POST /api/external/token/request`. Send as `Authorization: Bearer `. subscriptionKey: type: apiKey in: header name: external-gh-apim-sub-key description: >- Guardhouse API Management subscription key. Required on every request. The same value is used by all API consumers within a region — contact Guardhouse Support for the subscription key. ````