Account health

This is the page to read before you go to production. Everything else is an API; this is the part that decides whether your users trust the feature in month three.

Connections breakCopy Anchor Link

Not sometimes — routinely, and for ordinary reasons:

• A user changes the password an app password was issued under. Apple revokes every app-specific password when the Apple Account password changes.
• A Google or Microsoft token expires or is revoked in the admin console.
• A tenant administrator withdraws consent for the whole organisation.
• A user turns on two-factor authentication.
• An IMAP server rotates credentials or closes idle connections.

None of these is a failure of your integration or of Aux0. They are the providers working as designed. What matters is what happens next.

What aux0 doesCopy Anchor Link

1. Detects it rather than returning the provider's error to you. A revoked grant and a rate limit look identical at the HTTP layer; Aux0 tells them apart.
2. Marks the account needs_attention or disconnected, with a code.
3. Fires a webhook with that code and a sentence written for your end user, not for an engineer.
4. Queues sends instead of dropping them. Reads keep working on cached history.
5. Stops retrying. Hammering a provider that has pushed back is how an account gets restricted rather than merely interrupted.

The eventCopy Anchor Link

{
  "type": "account.needs_attention",
  "data": {
    "account": {
      "id": "acc_li_tom",
      "provider": "icloud",
      "end_user_id": "u_tom",
      "status": "needs_attention"
    },
    "attention": {
      "code": "password_changed",
      "message": "Apple revoked this app password when the Apple Account password changed.",
      "self_serve": true,
      "since": "2026-10-22T11:20:00Z"
    },
    "reconnect_url": "https://auth.aux0.com/r/2kd9fQmLp3"
  }
}

The codesCopy Anchor Link

self_serve: true means a hosted auth link fixes it and the user needs no help from your support team. Most of them are.

What your product should doCopy Anchor Link

The pattern that works:

1. On account.needs_attention with self_serve: true, show the user the message where they will see it, and a button pointing at reconnect_url.
2. Keep the feature visible but marked, rather than hiding it. A channel that silently stops is worse than one that says it needs a minute of attention.
3. On account.connected for the same account, clear the notice. Queued sends go out on their own.

The anti-pattern is treating it as an error: logging it, alerting your team, and waiting for a human to notice. These are routine, they are the user's to fix, and the user can fix them in under a minute.

PreventionCopy Anchor Link

aux0 does what can be done:

• Rate pacing inside each provider's own windows, rather than finding the limit by hitting it.
• One sync cursor per account, held across reconnects rather than restarted.
• Warm-up, so a newly connected account is not run at full rate on its first day.
• Backing off on the first sign of provider pushback.

What nobody can do is guarantee an account is never restricted. Automating a personal account is against most providers' terms, and we say so on the home page rather than in a footnote.