# Vault connection A connection is a link between a consumer (end-user, client, ...) and a integration (like Salesforce, Hubspot, Bamboo HR, Workday,...). It is the result of a consumer authorizing a integration to access their data. # Vault Connection state Using the Vault API, you can retrieve the [connections a consumer](https://developers.apideck.com/apis/vault/reference#operation/consumersOne) has or [all connections](https://developers.apideck.com/apis/vault/reference#operation/connectionsAll) for your account or a [single connection](https://developers.apideck.com/apis/vault/reference#operation/connectionsOne). This `state` property is important if you want to know if a connection is ready to be used. The various `state` values, indicates the state of a connection for consumer, during the different stages. The connection state is computed based on the connection flow below. ![Vault Connection flow](/guides/connection-states/connection-flow.png) ## Property state - available The state "available" is used for available integration(s) that are not yet added/enabled by the consumer. ![Vault Connection State - Available](/guides/connection-states/state-available.png) ## Property state - added The state "added" is used for available integration(s) that are added/enabled by the consumer. The integration is not yet authorised for OAuth. ![Vault Connection State - Added OAuth](/guides/connection-states/state-added-oauth.png) In case of non-OAuth integrations, the credentials are not yet entered. ![Vault Connection State - Added](/guides/connection-states/state-added.png) ## Property state - invalid The state "invalid" is used for integrations where the entered credentials are invalid. ![Vault Connection State - Invalid](/guides/connection-states/state-invalid.png) ## Property state - authorized The state "authorized" is only applicable for OAuth integrations, that requires additional configuration after authorization. Example: Xero uses OAuth, but for Apideck to connect, the consumer needs to select the desired tenant after authorization. ![Vault Connection State - Authorized](/guides/connection-states/state-authorized.png) ## Property state - callable The integration is successfully connected ✅. For OAuth integrations, this means that requested scopes are granted and the consumer has authorised the access to his instance. For non-OAuth integrations, this means that the entered credentials & configuration are valid. The validation happens by triggering an API request to specific endpoint towards the integrations API. ![Vault Connection State - Callable](/guides/connection-states/state-callable.png) ## Reacting to state changes without polling Rather than periodically polling the Vault API to check whether a connection's `state` has changed, you can subscribe to webhook events and react as changes happen. See the [Webhooks guide](/guides/webhooks) for how to subscribe. Vault emits the following events for connection state changes: - **`vault.connection.callable`** — fires the moment a connection transitions from any other state to `callable`. This is the "ready for API calls" signal, and it's the final event in a successful OAuth flow. - **`vault.connection.updated`** — a general-purpose event that fires whenever any connection data changes as a result of a Vault-driven action (adding/updating credentials, an OAuth callback, importing a connection, updating settings). Its payload includes the connection's current `state`. - **`vault.connection.disabled`** — fires when a connection's `enabled` property changes from `true` to `false`. - **`vault.connection.revoked`** — fires when OAuth access is explicitly revoked and that revocation is confirmed at the integration's side. - **`vault.connection.token_refresh.pending`** — for OAuth connectors, Vault refreshes tokens proactively ahead of expiry (and retries roughly every 15 minutes if a refresh attempt fails). This event fires on the *first* failed attempt — the connection stays `callable` for up to 48 hours while Vault keeps retrying, giving you an early warning before anything actually breaks. - **`vault.connection.token_refresh.failed`** — fires once that 48-hour retry window elapses with no successful refresh: credentials are cleared and the connection is no longer callable. This happens automatically as part of Vault's own retry cycle — you don't need to call anything yourself to get it. - **`vault.connection.downstream.degraded`** / **`vault.connection.downstream.recovered`** — a connection can stay `callable` while the integration itself is temporarily unreachable; these two events cover that separately from `state`. > > There's one case none of the events above cover: a request to the integration comes back > unauthorized even though the stored token or credentials didn't look expired or otherwise > invalid locally — for example, access was revoked on the integration's side earlier than its > recorded expiry, or the connector uses static (non-OAuth) credentials with no refresh cycle at > all. Vault still detects this and marks the connection invalid, but that specific path doesn't > emit a webhook event, and — since it isn't part of the token-refresh retry cycle — it won't > self-correct either. Calling [`validateConnectionState`](https://developers.apideck.com/apis/vault/reference#operation/validateConnectionState) > yourself (for example on a schedule) forces a fresh check and will emit > `vault.connection.token_refresh.failed` once that check's own refresh attempt exhausts the retry cycle; otherwise, > treat a 401/unauthorized response from your own Unified API or Proxy calls as a signal in its > own right for this specific case. See the [Webhook API reference](https://developers.apideck.com/apis/webhook/reference#tag/Webhooks) for how to subscribe and the full event payload shapes. ## Property enabled A connection can be enabled or disabled by the consumer. This is useful if you want to give the consumer the ability to disable a connection. When a connection is disabled, it will not be used for API calls. ![Vault Connection property - enabled](/guides/connection-states/property-enabled.gif) If you don't want to give the consumer the ability to disable a connection, you can disable the availability option when initialising the [Vault session](https://developers.apideck.com/apis/vault/reference#tag/Sessions) using the `allow_actions` setting. The `allow_actions` setting allows you to define which actions (disable, delete, ...) are available for the consumer. ![Vault Settings](/guides/connection-states/vault-session-settings.png) ## Property status This property on a connection refers to the status of the integration within the Apideck platform. More details can be found in the [Connector Statuses](/guides/connector-statuses) guide.