Disconnecting Integrations

When you no longer need a third-party integration, or when you need to reset credentials, Otesse provides a clean disconnection process. Disconnecting revokes access tokens, destroys stored credentials, disables sync jobs, and marks external references as stale — while preserving all previously synced data and configuration for potential reconnection.

Before You Disconnect

Consider the following before disconnecting an integration:

• Active sync jobs — Any running sync executions will be cancelled. Partially synced records from the current batch are preserved.
• Dependent features — If the Email Builder uses Postmark sender emails, disconnecting Postmark removes those options from the "From" dropdown.
• Other users — If other users in your organization have connections to the same integration, disconnecting your connection does not affect theirs.
• Data preservation — All data previously synced into Otesse is preserved. Disconnecting does not delete local copies of synced records.

Disconnection Flow

Step 1: Confirm

Click "Disconnect" on the connected provider. A confirmation dialog appears:

Disconnect [Provider]?

This will revoke access and delete all stored credentials. Any active sync jobs will stop. Previously synced data will be kept but marked as stale.

If the integration has active sync jobs, an additional warning shows the count of jobs that will be disabled.

Step 2: Disable Sync Jobs

Before revoking credentials, the system disables all active sync jobs to prevent failures:

• All SyncJob records for the connection are set to isEnabled = false
• Any currently running SyncExecution is cancelled (status = "cancelled", completedAt = now())

Step 3: Revoke OAuth Tokens (OAuth Providers Only)

For OAuth-authenticated providers:

1. The system calls the provider's token revocation endpoint
2. If the revocation call fails (provider unreachable, token already expired), the disconnection continues — revocation failure does not block the process
3. Both access tokens and refresh tokens are revoked separately

Step 4: Destroy Credentials

All stored credentials are destroyed with defense-in-depth:

1. The encrypted credential value is overwritten with an empty string (destroying the ciphertext)
2. The record is soft-deleted (isDeleted = true, isActive = false)

This two-step process ensures credentials are unrecoverable even if the soft-deleted record is later accessed.

Step 5: Update Statuses

Record	New Status
IntegrationConnection	revoked
IntegrationInstance	revoked (only if no other users are connected)
WebhookEndpoints	disabled
IntegrationHealth	unknown, health checks stopped

If other users in your organization still have active connections, the instance remains "connected" — only your personal connection is revoked.

Step 6: Mark External References

All ExternalReference records linked to the instance are marked as "stale." This preserves the mapping between local Otesse records and their provider counterparts without claiming the data is current.

Step 7: Audit Log

A detailed audit entry records:

• Who disconnected
• Which provider
• Whether OAuth revocation succeeded
• How many sync jobs were disabled
• How many credentials were deleted
• Timestamp and IP address

Data Retention After Disconnect

Data Type	After Disconnect	Rationale
Credentials	Ciphertext destroyed, records soft-deleted	Security: no recoverable credential data
Synced data (local records)	Kept in full	Business continuity: invoices, contacts, etc. remain usable
External references	Kept, marked as "stale"	Allows re-linking on reconnection
Sync job configurations	Kept, disabled	Configuration preserved for reconnection
Field mappings	Kept	Can be reused on reconnection
Audit logs	Kept permanently	Compliance: full audit trail
Webhook subscriptions (outbound)	Not affected	Outbound webhooks are org-scoped, not per-connection
Webhook endpoints (inbound)	Disabled, kept	Can be re-enabled on reconnection

Reconnecting After Disconnect

If you need to reconnect a previously disconnected provider:

1. Navigate to the All Integrations catalog
2. Click "Connect" on the provider (the button reappears after disconnection)
3. The system reuses the existing IntegrationInstance (status updated from "revoked" to "pending")
4. You authenticate with new credentials
5. Previously disabled sync jobs can be manually re-enabled
6. External references with "stale" status are updated to "synced" after the next successful sync

This reconnection flow preserves all previous configuration and data mappings, so you do not need to reconfigure sync jobs or field mappings from scratch.

Edge Cases

Scenario	Behavior
Disconnect while sync is running	Running execution is cancelled. Partially synced records are preserved
Admin disconnects another user's connection	Allowed if admin has settings.edit. Audit log records the admin as the actor
Last connection on an instance	Instance status changes to "revoked." Instance is preserved (not deleted)
Provider has dependent integrations	Warning shown: "Disconnecting may affect [dependent]. " Disconnection proceeds after confirmation
OAuth revocation fails	Logged as warning, disconnection continues. Provider token eventually expires on its own