> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usecobalt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Account Events

Account events alert you when an end-user's stored EHR credentials need attention. They're not tied to a specific RPA operation — Cobalt's authentication layer fires them when it detects a credential issue during any login attempt.

There are two account events:

* **`access_token.login_required`** — credentials are no longer valid; the user must re-authenticate via Cobalt Link before further operations can succeed.
* **`access_token.password_change_warning`** — the EHR is prompting the user to change their password (currently eClinicalWorks only). Re-authenticate proactively to avoid an interruption.

For both, surface `data.message` to the affected user and direct them to [Update Mode](/docs/link/update-mode) to refresh their credentials.

## Payload Envelope

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440030",
  "access_token_reference_id": "your-reference-id",
  "object": "event",
  "created": "2025-10-21T14:30:00.000Z",
  "type": "access_token.login_required",
  "data": {
    // Event-specific payload
  }
}
```

| Field                       | Type   | Description                                   |
| --------------------------- | ------ | --------------------------------------------- |
| `id`                        | string | Unique identifier for this event              |
| `access_token_reference_id` | string | Your reference ID for the affected end-user   |
| `object`                    | string | Always `"event"`                              |
| `created`                   | string | ISO 8601 timestamp when the event was created |
| `type`                      | string | The event type                                |
| `data`                      | object | Event-specific data payload                   |

## Event Types

<AccordionGroup>
  <Accordion title="access_token.login_required" icon="key-skeleton">
    Triggered when an end-user's stored EHR credentials are no longer valid (e.g. password changed in the EHR, account locked, or password expired). The user must re-authenticate via Cobalt Link before further operations can succeed.

    **Payload Example:**

    ```json theme={null}
    {
      "id": "550e8400-e29b-41d4-a716-446655440030",
      "access_token_reference_id": "clinic_1",
      "object": "event",
      "created": "2025-10-21T14:30:00.000Z",
      "type": "access_token.login_required",
      "data": {
        "access_token_reference_id": "clinic_1",
        "emr_instance_domain": "myclinic.eclinicalworks.com",
        "message": "Invalid credentials detected - login required.",
        "error_type": "password_expired"
      }
    }
    ```

    **Data Fields:**

    | Field                       | Type   | Description                                                      |
    | --------------------------- | ------ | ---------------------------------------------------------------- |
    | `access_token_reference_id` | string | Your reference ID for the affected end-user                      |
    | `emr_instance_domain`       | string | The EHR instance domain associated with the access token         |
    | `message`                   | string | Human-readable explanation, including any next-step instructions |
    | `error_type`                | string | Optional. Specific reason category (e.g. `password_expired`)     |
  </Accordion>

  <Accordion title="access_token.password_change_warning" icon="key">
    Triggered when an EHR (currently eClinicalWorks) prompts the user to change their password but the prompt was deferred. This is an early warning that a password change will be required soon.

    **Payload Example:**

    ```json theme={null}
    {
      "id": "550e8400-e29b-41d4-a716-446655440031",
      "access_token_reference_id": "clinic_1",
      "object": "event",
      "created": "2025-10-21T14:30:00.000Z",
      "type": "access_token.password_change_warning",
      "data": {
        "access_token_reference_id": "clinic_1",
        "emr_instance_domain": "myclinic.eclinicalworks.com",
        "message": "Password change required in eCW. After changing your password in eCW, please update your Cobalt account by following the instructions at https://docs.usecobalt.com/docs/link/update-mode"
      }
    }
    ```

    **Data Fields:**

    | Field                       | Type   | Description                                              |
    | --------------------------- | ------ | -------------------------------------------------------- |
    | `access_token_reference_id` | string | Your reference ID for the affected end-user              |
    | `emr_instance_domain`       | string | The EHR instance domain associated with the access token |
    | `message`                   | string | Human-readable explanation with next-step instructions   |
  </Accordion>
</AccordionGroup>