Disable, delete or re-authorize a connection: what each one does

A connection links one of your consumers to one provider account. There are three things you can do to it, and they have very different effects:

	Disable	Delete	Re-authorize
API call	`PATCH /vault/connections/{unified_api}/{service_id}` with `{"enabled": false}`	`DELETE /vault/connections/{unified_api}/{service_id}`	The customer clicks Authorize again in Vault
Credentials and settings	Kept	Removed	Credentials replaced, settings kept
Can it make API calls?	No, until it's enabled again	No	Yes, once it's callable
Virtual webhook syncing	Stops	Stops	Continues, or restarts once callable
Webhook event	`vault.connection.disabled`	`vault.connection.deleted`	`vault.connection.updated`, plus `vault.connection.callable` if it wasn't callable before
Customer needs to reconnect?	No, just enable it again	Yes, from scratch	It is the reconnect

Disable: pause a connection

Disabling keeps everything but stops the connection from being used. Use it to pause a customer temporarily, for example during a billing issue.

While it's disabled, its state is authorized instead of callable, and API calls for it return a 401 ConnectorCredentialsError ("Connector not authorized"). That looks the same as a broken connection, so check enabled on the connection before asking a customer to reconnect. Set enabled back to true to resume, with no action from the customer. You then receive vault.connection.updated and vault.connection.callable.

Delete: remove a connection completely

Deleting removes the stored credentials, settings and the connection's field mappings. Where the provider supports it, Apideck also asks the provider to revoke the access token, and removes webhooks it registered at the provider. This can't be undone. To connect again, the customer goes through the full connect flow.

The consumer itself isn't deleted, and its other connections keep working.

Re-authorize: fix a connection that stopped working

When a connection's state is invalid or its health is needs_auth (for example after a password change, a revoked app or an expired refresh token), the customer re-authorizes it in Vault. This keeps the same connection and its settings and replaces the credentials. See Why did my connection stop working?

Don't delete and re-add a connection to fix authorization. Re-authorizing is enough, and it keeps the settings the customer chose.

One connection per provider per consumer

A consumer can have only one connection to each connector for each Unified API. If one of your customers has two QuickBooks companies, for example, use a separate consumer ID for each company. See understanding consumers.

Disconnect (in Vault)

For OAuth connections, Vault also offers Disconnect. It revokes Apideck's access at the provider and clears the connection's credentials and settings, but keeps the connection itself. To use it again, the customer authorizes and enters any settings again. You receive vault.connection.updated, and vault.connection.revoked once the provider confirms.

In the Vault UI

These are the buttons your customers see on a connection in Vault, and the allow_actions value in the Vault session settings that controls each one:

Button	`allow_actions` value	What it does
Re-authorize	`reauthorize`	Re-authorize (OAuth connections)
Disable / Enable	`disable`	Disable or enable
Disconnect	`disconnect`	Disconnect (OAuth connections that are connected)
Delete	`delete`	Delete

If you don't set allow_actions, all of them are shown. To hide some, list only the ones you want. See the Vault guide.

Contact Apideck support through the Customer Portal (the Requests link at the top of this help center), your Slack channel with us, or support@apideck.com if you're unsure which one to use.