# 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, at which point 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; otherwise, treat a 401/unauthorized > response from your own Unified API or Proxy calls as the signal 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.