# Login Events

Fetches Finxact login **event** records — a stream of security-relevant events for tenant logins. A single input instance collects one of two event logs, selected via **Record Type**:

- **Login Activity** (`loginActivity`) — authentication events. Each record captures one login event with its `domainId`, `loginId`, per-login sequence `seq`, event timestamp `eventDtm`, `status`, and unique `logId`.
- **Login History** (`loginHist`) — credential/secret-change events. Each record captures one change with its `domainId`, `loginId`, `seq`, `eventDtm`, the prior secret value `oldVal`, `secretType`, and unique `logId`.

Both logs share the same shape and are ordered and cursored on `eventDtm`. Use this input to feed your SIEM, alert on authentication activity, and audit credential changes. To ingest both logs, add a second Login Events input with the other **Record Type**.

**Sync Type: Incremental**

## Prerequisites

- A provisioned Finxact tenant with access to the Finxact Console.
  - Production: `https://console.finxact.io`
  - Sandbox: `https://console-sandbox-server.dev-<pool>.finxact.io` (e.g. `dev-10`).
- An API client registered under the tenant with a role that grants **read** access to the `loginActivity` and/or `loginHist` resource you plan to ingest.
- The tenant subdomain (e.g. `acmebank`) and, for non-production tenants, the environment pool suffix (e.g. `dev-10`).
- The Monad worker's egress IP address must be added to the Finxact tenant's IP allowlist (or reachable via the required VPN). Finxact enforces network-level access control on the core-banking API — see [Networking](#networking) below.

### Obtain credentials in the Finxact Console

1. Sign in to the Finxact Console at `https://console.finxact.io` (production) or `https://console-sandbox-server.dev-<pool>.finxact.io` (sandbox).
2. Navigate to **Settings → API Clients**.
3. **Create** a new API client (or select an existing one dedicated to Monad).
4. Assign the client a role that grants **read** permission on the `loginActivity` / `loginHist` resource.
5. Copy the generated **Client ID** and **Secret** — the secret is shown once at creation time.
6. Note the tenant subdomain (e.g. `acmebank`) and, for non-production, the environment pool (e.g. `dev-10`). Together they form the base URL: `https://<tenant>.<pool>.finxact.io` (sandbox) or `https://<tenant>.finxact.io` (production).

## Configuration

### Settings

| Setting | Type | Required | Description |
| ------- | ---- | -------- | ----------- |
| Record Type | string | Yes | Which login event log to ingest: `login_activity` (Login Activity — authentication events) or `login_hist` (Login History — credential-change events). Each maps to a distinct Finxact endpoint; a single input collects one type. |
| Tenant | string | Yes | Finxact tenant subdomain (e.g. `acmebank`). Forms the base URL host. |
| Environment Pool | string | No | Environment pool suffix (e.g. `dev-10` for sandbox). Leave empty for production. |
| User Roles | array of strings | Yes | At least one role must grant read access to the selected resource. |
| Client ID | string | Yes | Tenant API `client_id`, sent as the `client_id` HTTP header. |
| Backfill Start Time | string | No | ISO-8601 timestamp for the first sync (e.g. `2024-01-01T00:00:00Z`). Leave empty to start from `now` (no historical backfill). Subsequent syncs are incremental and ignore this value. |
| Use Synthetic Data | bool | No | Generate synthetic demo records instead of connecting to Finxact. Useful for pipeline testing. |

### Secrets

| Secret | Type | Required | Description |
| ------ | ---- | -------- | ----------- |
| Client Secret | string | Yes | Tenant API client secret, sent as the `secret` HTTP header. |

## Networking

Finxact enforces network-level access control on the core-banking API. If the Monad worker cannot reach the tenant, or its egress IP is not on the allowlist, requests fail with **HTTP 403 Forbidden**. To resolve:

1. Identify the Monad worker's egress IP.
   - For Monad SaaS: see [Monad egress IP addresses](../../guides/egress-ip-addresses.mdx).
   - For self-hosted deployments: use your own cluster's outbound IP.
2. Add that IP to your Finxact tenant's allowlist via the Finxact Console (or coordinate with your Finxact deployment engineer).
3. If your tenant sits behind a required VPN, ensure the Monad worker is on the VPN.

## Troubleshooting

**`finxact authentication failed` (HTTP 401)**
The `client_id` / `secret` are wrong, or the role listed in **User Roles** does not grant read on the selected resource. Regenerate credentials in the Finxact Console and confirm the assigned role covers `loginActivity` / `loginHist` read.

**`finxact rejected the request at the network layer` (HTTP 403)**
Finxact's edge is refusing the connection before authentication runs. Confirm the Monad worker's egress IP is allowlisted at the tenant and that any required VPN is connected. See [Networking](#networking).

**No records returned despite recent login activity**
The initial backfill window may be too narrow. Set **Backfill Start Time** further back on the first sync. Note that `eventDtm` — not wall-clock time — drives the cursor, so records with an `eventDtm` earlier than the initial window are skipped. Also confirm **Record Type** matches the log you expect (authentication events vs. credential changes).

**`finxact 429` or repeated `finxact 5xx` errors**
Retryable — the input surfaces these so the framework retries on the next scheduled run. Persistent 429s indicate the tenant's contracted throughput is being exceeded; reduce sync frequency, or coordinate an increase with your Finxact account team.

## Related Articles

- [Finxact — loginActivity API](https://finxact.io/apis/detail-page/api_library/loginactivity/)
- [Finxact — loginHist API](https://finxact.io/apis/detail-page/api_library/loginhist/)
- [Finxact — Authentication](https://finxact.io/apis/detail-page/document/authentication/)
- [Finxact — Pagination, ordering, and limits](https://finxact.io/apis/detail-page/document/pagination-ordering-and-limits-filters/)
- [Finxact — Core and model API endpoints](https://finxact.io/apis/detail-page/document/core-and-model-api-endpoints/)
- [Finxact — API response codes](https://finxact.io/docs/document-detail/document/api-response-codes/)