The Ambiguity of API Disconnection

Connecting to an API is usually well-documented. The process of disconnecting, however, often remains obscure. This ambiguity becomes a significant problem during critical operations like user offboarding, incident response, or vendor security reviews. The term "disconnect" can imply vastly different actions, from simply disabling token refreshes to immediately purging all stored secrets. Treating these distinct operations as a single event leads to unexpected and often undesirable outcomes for users and systems alike.

If your system manages credentials, sessions, OAuth refresh tokens, service account bindings, or imported browser sessions, a clear revocation model is essential. Users must understand precisely what will cease to function, what data will be permanently deleted, and what information will persist after a revocation action.

Separate Revocation Actions

A common pitfall is providing a single, generic revocation endpoint, such as:

DELETE /connections/github

This single endpoint offers minimal clarity to the caller. It fails to specify whether it deletes only the connection record, revokes associated tokens, or severs the link entirely. This lack of granularity forces users to guess the impact of their action, leading to potential data loss or incomplete security measures.

A more robust approach involves distinguishing between different types of revocation. Consider these scenarios:

  • Token Revocation: This action invalidates specific access or refresh tokens, preventing further authentication using those credentials. The underlying connection or user account may remain active.
  • Session Invalidation: This revokes active user sessions across devices or applications. It forces users to re-authenticate but doesn't necessarily delete stored credentials or connection metadata.
  • Credential Deletion: This permanently removes sensitive credentials, such as API keys or secrets, associated with a connection. This is a destructive action and should be clearly distinguished from less severe revocation types.
  • Connection Deletion: This removes the record of the integration or connection itself, potentially including associated metadata and tokens, effectively severing the link between services.

Designing for User Understanding

To address this ambiguity, APIs should offer granular revocation options, each with a clear intent and documented outcome. Instead of a single DELETE /connections/:provider, consider distinct endpoints or parameters that specify the scope of revocation:

  • POST /connections/:provider/tokens/revoke: Specifically revokes all active tokens for a given connection.
  • POST /connections/:provider/sessions/invalidate: Invalidates all active user sessions for the connection.
  • DELETE /connections/:provider/credentials: Deletes the stored credentials associated with the connection.
  • DELETE /connections/:provider: Deletes the connection record entirely, potentially including associated metadata and tokens.

When a user initiates a revocation, the API should provide immediate feedback detailing what actions have been taken and what the consequences are. This could be an explicit confirmation message, an audit log entry, or updated status information within the user interface.

The Impact on Offboarding and Security

During offboarding, precise revocation is critical. If an employee's access is revoked, the system needs to know whether their associated service accounts or API keys are immediately deleted or merely disabled. Failing to delete dormant credentials can leave security holes.

In incident response, the ability to quickly and precisely revoke specific access tokens or sessions without disrupting unrelated operations is paramount. A blunt instrument that deletes everything can cause more harm than good.

Transparency is Key

The core principle is transparency. Users, whether they are developers integrating services, administrators managing access, or end-users connecting accounts, need to understand the implications of every action they take regarding API access. This means:

  • Clear Documentation: Every revocation mechanism must be thoroughly documented, explaining what is affected and what is not.
  • Granular Controls: Provide distinct options for revoking tokens, sessions, credentials, or entire connections.
  • Explicit Confirmation: When a revocation occurs, confirm the specific actions taken and their effects to the user.
  • Auditable Actions: Maintain logs that clearly show when and by whom specific revocation actions were performed.

Designing API access revocation with clarity and granularity is not just a matter of good UX; it's a fundamental security practice that prevents data leakage and ensures predictable system behavior during critical lifecycle events.