Account Events

Account events alert you when an end-user’s stored EHR credentials need attention. They’re not tied to a specific 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. Re-authenticate proactively to avoid an interruption.

For both, surface data.message to the affected user and direct them to Update Mode to refresh their credentials.

Identifying the credential

A connection can hold more than one set of EHR credentials, and an account event is always about exactly one of them. Both events carry credential_id, the ID of that credential set, so you do not have to guess which login needs attention. credential_id is also the ID the credential endpoints take, so you can act on the credential straight from the event:

Disable a credential — stop Cobalt using it for EHR sessions, leaving it in place.
Delete a credential — remove it entirely.
Enable a credential — put a disabled credential back into rotation.

The last active credential set on a connection cannot be disabled or deleted.

credential_id is present on the envelope and repeated inside data. Treat it as nullable: in the rare case where Cobalt cannot resolve the credential set behind an event, it is null. Fall back to access_token_id to identify the connection.

Payload Envelope

{
  "id": "550e8400-e29b-41d4-a716-446655440030",
  "access_token_reference_id": "your-reference-id",
  "access_token_id": "550e8400-e29b-41d4-a716-446655440000",
  "credential_id": "550e8400-e29b-41d4-a716-446655440010",
  "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
`access_token_id`	string	UUID of the specific connection (link access token) that generated this event
`credential_id`	string	UUID of the credential set the event is about. Pass it to the credential endpoints to disable, delete, or re-enable that credential. `null` if Cobalt could not resolve it
`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

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:

{
  "id": "550e8400-e29b-41d4-a716-446655440030",
  "access_token_reference_id": "clinic_1",
  "access_token_id": "550e8400-e29b-41d4-a716-446655440000",
  "credential_id": "550e8400-e29b-41d4-a716-446655440010",
  "object": "event",
  "created": "2025-10-21T14:30:00.000Z",
  "type": "access_token.login_required",
  "data": {
    "access_token_reference_id": "clinic_1",
    "credential_id": "550e8400-e29b-41d4-a716-446655440010",
    "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
`credential_id`	string	UUID of the credential set that can no longer sign in. `null` if Cobalt could not resolve it
`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`)

access_token.password_change_warning

Triggered when an EHR 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:

{
  "id": "550e8400-e29b-41d4-a716-446655440031",
  "access_token_reference_id": "clinic_1",
  "access_token_id": "550e8400-e29b-41d4-a716-446655440000",
  "credential_id": "550e8400-e29b-41d4-a716-446655440010",
  "object": "event",
  "created": "2025-10-21T14:30:00.000Z",
  "type": "access_token.password_change_warning",
  "data": {
    "access_token_reference_id": "clinic_1",
    "credential_id": "550e8400-e29b-41d4-a716-446655440010",
    "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
`credential_id`	string	UUID of the credential set whose password is expiring. `null` if Cobalt could not resolve it
`emr_instance_domain`	string	The EHR instance domain associated with the access token
`message`	string	Human-readable explanation with next-step instructions

Introduction

Guides

Account Events

Identifying the credential

Payload Envelope

Event Types

​Identifying the credential

​Payload Envelope

​Event Types

Identifying the credential

Payload Envelope

Event Types