Token Refresh Lifecycle Events

Apideck automatically manages OAuth token refresh for all your consumers' connections. When a token refresh starts failing, the connection enters a retention window - a grace period where credentials are preserved and automatic retries continue on every API request.

Three webhook events give you full visibility into this lifecycle so you can respond proactively instead of waiting for a hard failure.

This event fires the first time a token refresh fails for a previously healthy connection. The connection has entered a degraded state, but credentials are still valid and the connection is still callable - each subsequent API request will automatically retry the token refresh. If a retry succeeds, the connection self-heals and you'll receive a recovered event.

This event fires only once per degradation cycle, not on every failed retry. You will not receive an event storm during an extended provider outage.

Payload fields on the connection entity:

Recommended actions:

1. Wait and monitor. Most refresh failures are transient (provider maintenance, rate limits, temporary network issues) and resolve automatically within minutes to hours.

2. Note the credentials_expire_at deadline. If you haven't received a recovered event as the deadline approaches, consider prompting the consumer to re-authorize proactively.

3. Optionally alert your team to investigate the downstream provider if the connection is business-critical.

This event fires when a token refresh succeeds after previous failures - the connection transitions from pending_refresh back to ok. The problem resolved itself, credentials are valid, the retention window is closed, and the connection is fully healthy.

Payload fields on the connection entity:

No action is required. If you surfaced a warning based on the earlier pending event, you can clear it. No consumer action is needed.

This event fires when the retention window has expired and all automatic refresh retries have failed. Credentials have been permanently cleared and the connection is no longer functional.

Payload fields on the connection entity:

Recommended actions:

1. The consumer must re-authorize. Direct them to your Vault session or Hosted Vault URL to complete the OAuth flow again.

2. Any API calls for this connection will fail until re-authorization is complete.

Not all token errors are permanent. Some OAuth providers, like QuickBooks Online is a well-known example and returns responses that look like permanent token failures (HTTP 401, invalid_grant) during what turns out to be a transient issue: a maintenance window, high load, or an internal timeout on their side. From the HTTP response alone, there's no way to tell the difference.

Apideck applies a retention window rather than immediately clearing credentials, giving the provider time to recover while keeping the connection callable.

How Apideck classifies errors:

The credentials_expire_at field on the pending event tells you which category you're in: if it's present, you're in the 48-hour window for an ambiguous error. If it's absent, the error was clearly transient and retries will continue indefinitely.

Happy path - connection self-heals:

10:00  Connection is healthy, token refreshes succeed normally

10:15  Token refresh fails
       → vault.connection.token_refresh.pending
         health: "pending_refresh"
         credentials_expire_at: "2026-03-27T10:15:00Z"
         last_refresh_failed_at: "2026-03-25T10:15:00Z"

10:45  API call triggers retry → still fails → no new event fired

11:30  API call triggers retry → succeeds!
       → vault.connection.token_refresh.recovered
         health: "ok"

Unhappy path - credentials expire:

10:15  → vault.connection.token_refresh.pending
         credentials_expire_at: "2026-03-27T10:15:00Z"

       ... 48 hours of failed retries, no additional events ...

Mar 27, 10:15  Retention window expires, credentials cleared
       → vault.connection.token_refresh.failed
         health: "needs_auth"

To start receiving these events, update your webhook configuration in the Apideck Admin to subscribe to any combination of:

• vault.connection.token_refresh.pending

• vault.connection.token_refresh.recovered

• vault.connection.token_refresh.failed

You don't need to subscribe to all three. If you only want to know when re-authorization is needed, failed alone is sufficient. Adding pending gives you early warning; adding recovered lets you automatically clear any alerts you've raised.

All three events include the full connection entity - service ID, unified API, consumer ID, and connection health, so you can identify exactly which consumer and integration is affected.

Will I get flooded with pending events during an outage? No. The pending event fires exactly once when the connection first enters pending_refresh. Subsequent failed retries don't generate additional events.

Can I still make API calls while a connection is pending_refresh? When a connection is first set to pending_refresh, there is a brief cooldown period during which downstream requests are blocked to give the provider's endpoint time to recover. Once the cooldown has passed, API calls using the connection will resume and each call will automatically attempt to refresh the token.

What if the connection recovers and then fails again later? You'll receive a new pending event for the new degradation cycle. Each pending/recovered/failed sequence is independent.

Is credentials_expire_at always present on the pending event? No. It's only present for ambiguous token errors (4xx, invalid_grant) where there's a finite 48-hour retention window. For clearly transient errors (5xx, network failures), credentials are retained indefinitely and the field is omitted.

The provider returned invalid_grant — is the token definitely dead? Not necessarily. Some providers (notably QuickBooks Online) return invalid_grant during maintenance or high load even when the token is still valid. Apideck treats these as ambiguous and applies the 48-hour retention window with automatic retries. If the issue was transient, the connection will self-heal and you'll receive a recovered event.