# 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 the access token on demand: when a request comes in and the access token is close to expiry, Vault uses the refresh token to get a new one. There is no background retry loop: after a failed attempt, the next request tries again once a short cooldown has passed. (For some connectors, Vault also refreshes on a schedule purely to keep the refresh token itself from expiring. If that scheduled refresh fails, it sends the same events.) This event fires on the *first* failed attempt. The connection stays `callable` while Vault keeps the credentials, giving you an early warning before anything actually breaks.
- **`vault.connection.token_refresh.failed`**: fires when a refresh attempt fails and at least 48 hours have passed since the first failed attempt; credentials are then cleared and the connection is no longer callable. There is no timer for this: the event is sent on the first failed refresh attempt after the 48 hours, which happens when a request comes in or, for some connectors, on the scheduled refresh. It also fires immediately if a forced refresh from `validateConnectionState` fails; in that case the connection is marked `invalid` and credentials are not cleared.
- **`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.