Skip to main content
If an integration appears connected but its workflows are not triggering, the saved credential may no longer be usable even though its last known status is still VALID. Check the credential status and monitoring logs, then ask the user to reconnect if Paragon has marked the credential INVALID.

​
Symptoms

  • The integration appears connected in your app or the Connect Portal.
  • Enabled workflows stop triggering or show no recent executions.
  • Opening integration settings produces connection errors.
  • paragon.getUser() returns credentialStatus: "VALID", but a request to the provider fails.
  • After another attempt to use the connection, the status changes to INVALID or the Connect Portal displays a reconnect warning.

​
Cause

credentialStatus is Paragon’s last known credential state. A credential can expire or be revoked outside Paragon, and Paragon cannot detect that change until it attempts to use or refresh the credential and receives a failure that indicates the connection cannot recover. This is why an inactive integration can continue to appear connected after its credential becomes unusable. Normal API errors do not always mean a credential is invalid. Paragon must distinguish a permanent credential failure from a temporary error, permissions error, or rate limit. Marking a credential INVALID does not delete the user’s connection. It marks the connection as requiring attention, stops it from being treated as enabled, and allows the Connect Portal to prompt the user to reconnect.

​
Fix

​
1. Check the current credential status

Call paragon.getUser() and inspect the integration’s credentialStatus:
The Users API documentation recommends showing a reconnection prompt whenever credentialStatus is not "VALID".

​
2. Review credential and workflow logs

In the Paragon dashboard, open Monitoring > All Logs. Filter by the affected User ID and Integration ID, then look for:
  • Failed credential refresh events
  • Workflow failures caused by authentication errors
  • The most recent successful workflow or credential refresh
Credential refresh events are currently available for select integrations. An absence of credential events does not prove the credential is valid.
Monitoring > All Logs is the right place for credential refresh events (attempted / failed / succeeded) for a specific user and integration, but All Logs doesn’t show workflow runs. Workflow executions and step-level auth errors are under Monitoring > Workflows.

​
3. Reconnect an invalid credential

If credentialStatus is INVALID, prompt the user to reconnect through the Connect Portal. For a Headless Connect Portal, start the same installation flow used for the original connection. In a multi-account integration, pass the affected credential ID so the correct account is replaced. Do not remove the connection solely because it is invalid. Reconnecting preserves the user’s intent to use the integration. If the user wants to remove it instead, follow the Users API instructions for disconnecting integrations.

​
4. Contact support if the status remains VALID

If the provider rejects requests but credentialStatus remains VALID, send Paragon Support:
  • Project ID
  • Connected User ID
  • Integration type
  • Credential ID, for multi-account connections
  • Workflow execution or request ID
  • Exact provider error and timestamp
  • The last known successful execution
This information helps determine whether the provider returned a temporary error, a permanent credential failure, or an error Paragon did not classify correctly.

​
Prevention

​
Notify your team about credential failures

Configure a Credential Failure Event Destination. The event is sent when an OAuth refresh fails in a way that cannot be retried and the credential is marked invalid. Use the event’s User ID and integration type to notify the affected user to reconnect. Webhook Event Destinations are available on paid plans and must be configured by a project Admin. You can also configure Workflow Failure notifications to catch scheduled work that fails after a connection problem. Credential Failure events report failures after they are detected. They do not predict when a provider will revoke a token or when a customer-managed secret will expire.