Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

docs(changelog): introduce connected_accounts revoke endpoint

Zen Agentdf9298aeebc7
diff --git a/docs/content/changelog/05-12-26-connected-accounts-revoke.mdx b/docs/content/changelog/05-12-26-connected-accounts-revoke.mdx
new file mode 100644
index 000000000..f4d286966
--- /dev/null
+++ b/docs/content/changelog/05-12-26-connected-accounts-revoke.mdx
@@ -0,0 +1,60 @@
+---
+title: "New Endpoint: Revoke OAuth 2.0 Tokens for a Connected Account"
+description: "Programmatically revoke a connected account's tokens at the upstream provider"
+date: "2026-05-12"
+---
+
+You can now programmatically revoke a connected account's OAuth 2.0 tokens at the upstream provider, giving you explicit control over when credentials are killed at the third-party — instead of relying on deletion or natural token expiry.
+
+### The Endpoint
+
+```http
+POST /api/v3.1/connected_accounts/{nanoid}/revoke
+```
+
+On success, the connection transitions to `REVOKED` and the response reports which token subjects were killed at the provider on this call.
+
+**Example request:**
+
+```bash
+curl -X POST 'https://backend.composio.dev/api/v3.1/connected_accounts/ca_1a2b3c4d5e6f/revoke' \
+ --header 'x-api-key: <YOUR_API_KEY>'
+```
+
+**Example response (`200 OK`):**
+
+```json
+{
+ "revoked_tokens": ["access_token", "refresh_token"],
+ "connected_account": {
+ "id": "ca_1a2b3c4d5e6f",
+ "status": "REVOKED"
+ }
+}
+```
+
+The `revoked_tokens` array lists the subjects revoked at the provider during this call. An empty array means the connection was already in a revoked state and no upstream dispatch was issued.
+
+### Status Codes
+
+| Code | Meaning |
+|------|---------|
+| `200` | Connection revoked (or already revoked — see `revoked_tokens`) |
+| `400` | Toolkit is not OAuth 2.0 or has no revoke configuration |
+| `404` | Connected account does not exist or its parent auth config was removed |
+| `409` | Connection is not in a revokable state (only `ACTIVE` and already-`REVOKED` are accepted) |
+| `500` | Database failure or every upstream revoke dispatch failed |
+
+### Revoke Is Not Automatic on Delete (Today)
+
+Deleting a connected account or a project does **not** currently revoke tokens at the upstream provider — the credentials are removed from Composio but may remain live at the third-party until they expire naturally. If you need credentials killed at the provider, follow **revoke-then-delete** semantics: call `POST /revoke` first, then issue the delete.
+
+In a future release, we may extend delete to cascade into revoke automatically. We'll announce this separately before changing the behavior; until then, treat the two steps as independent.
+
+### Revoke Is Best-Effort
+
+Some providers do not expose a programmatic way to revoke one or both token subjects (for example, an access token but no refresh-token revoke route, or no revoke endpoint at all). In those cases, Composio revokes whatever the provider supports and the `revoked_tokens` array reflects exactly what was killed. Always read `revoked_tokens` to confirm which subjects were affected — do not assume both `access_token` and `refresh_token` were revoked on every call.
+
+### Externally Revoked Tokens
+
+If a user revokes the connection directly with the provider (for example, removing the app from their account on the provider's website), the upstream revoke call from this endpoint may return an error. Such connections are eventually detected and marked as `EXPIRED` by the platform — you do not need to take additional action, but you should expect the revoke call itself to fail in that window.