Internal

Force-invalidate connector connections

Server-to-server endpoint supporting exact connection, user, immutable credential-org, connector, or combined targets. Product/service principals are bound to configured connector(s) and selector classes. Global control requires an explicit platform_admin principal. Matches become invalidated tombstones; credentials are cleared and upstream revocation is attempted.

post/v1/internal/connections/invalidate

Request

Base URL: / (relative, and the document was published on a file host, not at the API’s origin)
URL: /v1/internal/connections/invalidate
Auth: one of:
- API key in header X-Connector-Signature
- HTTP bearer

Request body

connection_idstring nullable

Optional exact MCPConnection UUID target.

connectorstring

Connector slug.

org_idstring nullable

Optional WorkOS organization target.

reasonstring nullable

Semantic revocation reason.

workos_user_idstring

WorkOS user id used to resolve bearer tokens into local users.

Example request

{
  "connection_id": "123e4567-e89b-12d3-a456-426614174000",
  "connector": "canvas",
  "org_id": "org_01HABCDEF",
  "reason": "subscription_ended",
  "workos_user_id": "user_01HABCDEF"
}

Response

Invalidation result.

failuresinteger

Number that could not be tombstoned.

invalidatedboolean required

Always true on successful handling, including no-op unknown users.

matchedinteger

Number of matching connection rows.

revokedinteger

Number retained as revoked tombstones.

Example response

{
  "invalidated": true,
  "matched": 1,
  "revoked": 1
}

Changes

No recorded changes to this operation across all 50 revisions of this API.