@devries-cameron20 / composio Mirror · read-only / commits / df9298aee
Fork 0

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

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 21:00 UTC

docs(changelog): introduce connected_accounts revoke endpoint

Add a customer-facing changelog entry for the new POST /api/v3.1/connected_accounts/{nanoid}/revoke endpoint, documenting revoke-then-delete semantics, best-effort behavior, and how externally revoked connections are handled. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> Co-authored-by: sarthak <sarthak@composio.dev>

Zen Agent committed May 12, 2026 at 07:11 UTC df9298aeebc7f5df324e98dd5a1ae11194697b3b
1 file changed +60
docs/content/changelog/05-12-26-connected-accounts-revoke.mdx new
+60
@@ -0,0 +1,60 @@
1 +---
2 +title: "New Endpoint: Revoke OAuth 2.0 Tokens for a Connected Account"
3 +description: "Programmatically revoke a connected account's tokens at the upstream provider"
4 +date: "2026-05-12"
5 +---
6 +
7 +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.
8 +
9 +### The Endpoint
10 +
11 +```http
12 +POST /api/v3.1/connected_accounts/{nanoid}/revoke
13 +```
14 +
15 +On success, the connection transitions to `REVOKED` and the response reports which token subjects were killed at the provider on this call.
16 +
17 +**Example request:**
18 +
19 +```bash
20 +curl -X POST 'https://backend.composio.dev/api/v3.1/connected_accounts/ca_1a2b3c4d5e6f/revoke' \
21 + --header 'x-api-key: <YOUR_API_KEY>'
22 +```
23 +
24 +**Example response (`200 OK`):**
25 +
26 +```json
27 +{
28 + "revoked_tokens": ["access_token", "refresh_token"],
29 + "connected_account": {
30 + "id": "ca_1a2b3c4d5e6f",
31 + "status": "REVOKED"
32 + }
33 +}
34 +```
35 +
36 +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.
37 +
38 +### Status Codes
39 +
40 +| Code | Meaning |
41 +|------|---------|
42 +| `200` | Connection revoked (or already revoked — see `revoked_tokens`) |
43 +| `400` | Toolkit is not OAuth 2.0 or has no revoke configuration |
44 +| `404` | Connected account does not exist or its parent auth config was removed |
45 +| `409` | Connection is not in a revokable state (only `ACTIVE` and already-`REVOKED` are accepted) |
46 +| `500` | Database failure or every upstream revoke dispatch failed |
47 +
48 +### Revoke Is Not Automatic on Delete (Today)
49 +
50 +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.
51 +
52 +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.
53 +
54 +### Revoke Is Best-Effort
55 +
56 +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.
57 +
58 +### Externally Revoked Tokens
59 +
60 +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.