Model a connection separately from the user session
Identify whether the connection belongs to a person, workspace, or shared service account. Store tenant, provider, external account identifier, installing actor, granted scopes, status, and credential version. A user logging out of your application should not accidentally delete a workspace-owned integration.
Define who may connect, reconnect, inspect sync status, and disconnect. Recheck those permissions at each action. Shared integration access must not inherit authority merely because one user once completed a provider login.
Bind consent to the intended tenant and action
Create a short-lived server-side authorization attempt tied to the initiating session, provider, target tenant, and permitted return path. Verify that attempt when processing the callback. Do not trust a tenant ID carried through an unsigned query parameter.
Use exact registered redirect URIs and request the minimum scopes needed for the selected capability. Explain what account and organization will be connected. A user switching workspaces in another tab must not retarget the original authorization attempt.
Store retrievable credentials in a protected server boundary
Your worker may need to present access and refresh tokens to the provider, so use encrypted storage or a managed secret system with limited decryption authority. Keep tokens out of browser bundles, ordinary JSON responses, logs, traces, and support exports.
Record expiry, granted scopes, provider metadata, and credential version beside the protected material. Avoid confusing the provider access token with your application session. Rotate encryption keys through an explicit versioned process so existing connections remain recoverable.
Coordinate refresh across concurrent workers
Several jobs may discover an expired access token at once. Serialize refresh for a connection using a durable lock, lease, or compare-and-swap strategy, and recheck the credential version after acquiring ownership. Persist replacement token material atomically.
Some providers rotate refresh tokens or apply reuse detection. Follow their documented rules for concurrent refresh and ambiguous network outcomes. Do not repeatedly replay an old refresh token after a timeout without understanding whether the provider already replaced it.
Keep synchronization scoped and resumable
Bind every sync job to tenant, connection ID, credential generation, and a durable cursor. Apply provider quotas and bounded concurrency. Map external identifiers inside the connection scope so similar IDs in two provider accounts cannot collide.
Separate temporary provider outages from missing scope, revoked consent, and deleted external resources. Retry transient failures with backoff, but pause work and request reconnection when credentials are permanently invalid. Reconnection should verify the selected external account before resuming an existing cursor.
Fence work before removing local credentials
Mark the connection disconnecting and advance its generation so queued jobs cannot continue using the old authority. Stop new dispatch, handle in-flight operations according to policy, and revoke provider tokens where supported. Then remove local credential material.
Define what happens to imported data, provider webhooks, and scheduled syncs. A local disconnect does not automatically delete remote data or revoke every provider session. Explain the completed scope to the administrator and record any revocation failure requiring follow-up.
Test consent and lifecycle races
Test callback replay, wrong sessions, workspace changes, insufficient scopes, external-account changes, simultaneous refresh, rotated tokens, lost refresh responses, and disconnect during a sync. Verify that old job generations cannot publish new results after disconnection.
Track connection health, oldest sync age, refresh failures, reconnect requests, and revocation outcomes using safe identifiers. Provide a diagnostic screen that shows status and required action without exposing secret material.
Apply the security guidance to your provider and infrastructure
Use the authorization-code flow with the protections supported and required by the provider, including PKCE and request-bound callback validation. Follow the provider contract and OWASP guidance rather than implementing a generic redirect handler from memory.
Build a more dependable Next.js application
Endurance Softwares helps teams design, build, test, and operate production-ready Next.js platforms.