> For AI agents: [llms.txt](https://docs.trustedauth.com/llms.txt) provides a Markdown index of this documentation.

# Authentication events

Authentication events notify you when users successfully authenticate or when authentication attempts fail. When an authentication event is triggered, IDaaS sends an HTTP POST request to your configured webhook URL with a JSON payload containing the event details.

## Payload structure

Every authentication event payload has this structure:

```json
{
  "id": "019adb89-60dd-750e-90a3-e860c924aa29",
  "type": "authentication.succeeded",
  "accountId": "c8485a88-4fd0-4248-8dcd-fb4ac0749fb7",
  "eventTime": "2025-12-01T20:10:04Z",
  "data": {
    // Event-specific data here
  }
}
```

The `data` object contains event-specific fields. See the event examples later on this page for the full `data` object for each event type.

### Top-level fields

| Field       | Type   | Description                                                |
| ----------- | ------ | ---------------------------------------------------------- |
| `id`        | string | Unique identifier for this webhook delivery                |
| `type`      | string | The event that occurred (e.g., `authentication.succeeded`) |
| `accountId` | string | Your account identifier                                    |
| `eventTime` | string | When the event occurred (ISO 8601 format)                  |
| `data`      | object | Details about what happened (varies by event type)         |

## Event types

### authentication.succeeded

Triggered when a user successfully authenticates to IDaaS.

**Example payload:**

```json
{
  "id": "019adb89-60dd-750e-90a3-e860c924aa29",
  "type": "authentication.succeeded",
  "accountId": "c8485a88-4fd0-4248-8dcd-fb4ac0749fb7",
  "eventTime": "2025-12-01T20:10:04Z",
  "data": {
    "subject": "f7475916-56ab-44a1-ab8a-3d4407baa102",
    "subjectName": "john.smith",
    "subjectType": "USER",
    "resourceName": "Administration Portal",
    "sourceIp": "127.0.0.1",
    "token": "OTP",
    "entityAttributes": {
      "registrationRequired": true
    }
  }
}
```

The `data` object includes the following fields:

| Field              | Description                                                                      |
| ------------------ | -------------------------------------------------------------------------------- |
| `subject`          | ID of the user who authenticated                                                 |
| `subjectName`      | Username of the user who authenticated                                           |
| `subjectType`      | Always `USER` for user authentications                                           |
| `resourceName`     | Where the authentication occurred (e.g., "Administration Portal", "User Portal") |
| `sourceIp`         | IP address from which the authentication was attempted                           |
| `token`            | Authentication method used (e.g., "OTP", "PASSWORD", "FIDO")                     |
| `entityAttributes` | Additional details about the authentication event, when available (see below)    |

When present, the `entityAttributes` object can include these fields:

- `registrationRequired` - Whether user registration is required

### authentication.failed

Triggered when a user's authentication attempt fails.

**Example payload:**

```json
{
  "id": "019adb89-60dd-750e-90a3-e860c924aa29",
  "type": "authentication.failed",
  "accountId": "c8485a88-4fd0-4248-8dcd-fb4ac0749fb7",
  "eventTime": "2025-12-01T20:10:04Z",
  "data": {
    "subject": "f7475916-56ab-44a1-ab8a-3d4407baa102",
    "subjectName": "john.smith",
    "subjectType": "USER",
    "resourceName": "Administration Portal",
    "sourceIp": "127.0.0.1",
    "token": "OTP"
  }
}
```

This event uses the same `data` structure as `authentication.succeeded`, but does not include `entityAttributes`.

| Field          | Description                                                                           |
| -------------- | ------------------------------------------------------------------------------------- |
| `subject`      | ID of the user who attempted authentication                                           |
| `subjectName`  | Username used in the authentication attempt                                           |
| `subjectType`  | Always `USER` for user authentications                                                |
| `resourceName` | Where the authentication was attempted (e.g., "Administration Portal", "User Portal") |
| `sourceIp`     | IP address from which the authentication was attempted                                |
| `token`        | Authentication method that was attempted (e.g., "OTP", "PASSWORD", "FIDO")            |