Why did my connection stop working? Common causes and how to fix them

A connection that worked yesterday can start failing today without anything changing in your code. API calls return 401, the connection shows as needing authorization in Vault, or you receive a vault.connection.token_refresh.failed webhook. Almost always, something changed on the provider's side: a token expired, access was revoked, or the user who connected the account lost their access.

This article explains how to check a connection, how to fix it, and the most common causes by provider.

Get the connection from the Vault API:

GET https://unify.apideck.com/vault/connections/{unified_api}/{service_id}

Look at two fields:

• state: the connection is ready to use when this is callable.

• health:

- ok means everything is fine.

- pending_refresh means a token refresh is failing, but Apideck keeps retrying and the connection still works for now.

- needs_auth means the consumer has to authorize again.

To get these changes as they happen instead of polling, subscribe to the token refresh webhooks. See Token Refresh Lifecycle Events.

1. Try a validation first. For OAuth connectors, POST /vault/connections/{unified_api}/{service_id}/validate forces a fresh token refresh. If the problem was temporary, this brings the connection back without involving the consumer.

2. Ask the consumer to re-authorize. If validation doesn't help, send them back to Vault (a new Vault session or your Hosted Vault link) to connect again. For API-key connectors, they enter a new key or password there. See How to create a Vault session and mail it to a consumer?

3. Fix the cause on the provider's side, using the list below, so it doesn't happen again.

• Someone disconnected or uninstalled your app in the provider, or an admin revoked its access.

• HiBob: disconnecting takes two steps. The consumer has to disconnect in Apideck and uninstall the app in Bob. If they only do one, the connection either keeps failing with 401s or still looks connected.

• Digits: uninstalling your app from an organisation revokes its tokens.

Many connections act as the person who authorized them. If that user is deactivated, loses their admin rights, or changes or lets their password expire, the connection stops working. Examples:

• Twinfield: the user is deleted, disabled or locked, or their password expires.

• Visma eAccounting and Spiris: the user changes their Visma Online password. The connection keeps looking healthy until the next call fails.

• Ceridian Dayforce and Cezanne HR: the integration user's password expires.

• Sage HR: the admin who enabled API access loses admin rights.

• sevDesk, Recruitee and AlexisHR: the user who created the token is removed or changes it.

Tip: connect with a dedicated integration user whose password doesn't expire and that nobody uses day to day.

• API keys or tokens with an expiry date: GitHub Server and GitLab Server personal access tokens, Planhat, Humaans and JumpCloud keys. Apideck can't renew these. The consumer creates a new one and enters it in Vault.

• Regenerated keys: in Alegra, Kenjo and similar tools, regenerating or editing a key invalidates the old one immediately.

• Your own app's credentials: a Microsoft Entra client secret (Business Central, Outlook) lasts at most 24 months. ADP Workforce Now certificates expire after two years. When yours expires, every connection using it stops working, so put renewal in your calendar.

• NetSuite: access tokens don't expire on their own. The connection stops if someone revokes or regenerates the token, deletes the Integration Record, or changes the role. Refreshing a NetSuite sandbox also removes the token. See NetSuite: "Invalid login attempt" and missing permissions.

• Sage Intacct REST: if the authorizing user signs in to the Sage Intacct web app, the connection's token is invalidated (error REST-2102). Use a dedicated integration user.

• Zoho Books and Zoho CRM: Zoho keeps at most 20 authorizations per user. Connecting a 21st time silently revokes the oldest.

• Google (Drive, Workspace, Contacts): while your Google app is in *Testing* status, every authorization expires after 7 days. Publish the app to stop this.

• Amazon Seller Central: sellers have to re-authorize your app every 365 days.

• QuickBooks and Intuit Enterprise Suite: authorizations have a maximum lifetime of 5 years, after which the consumer re-authorizes.

Some providers expire authorizations after a period of inactivity. For most OAuth connectors, Apideck renews the authorization in the background so that an unused connection stays alive. A few providers don't allow this, and a connection left unused for that long has to be re-authorized:

• Microsoft Dynamics 365 Business Central: 90 days

• Fortnox: 45 days

• Pennylane: 90 days

• JobAdder: 2 weeks

• QuickBooks and Intuit Enterprise Suite: some 400/401/403 errors are QuickBooks locking a company file because two requests reached it at the same time. Examples are a SystemFault, error code 100 or 140, or "company locked out". Apideck treats these as temporary and doesn't break the connection. Retry after a short pause.

• Exact Online: a 403 AppScopeViolated means your Exact app registration is missing a permission. The connection still shows as connected, but those calls fail until the permission is added to your app.

• Token Refresh Lifecycle Events

• How to detect when integrations get connected or disconnected?

• Understanding Vault and Authentication