# Revoke a connected account at the provider

**Documentation:** /reference/api-reference/connected-accounts/postConnectedAccountsByNanoidRevoke

Best-effort upstream revocation. On success, the connection transitions to REVOKED. Returns 400 when the toolkit does not support programmatic revocation, 409 when the connection is not in a revokable state, 500 when every upstream dispatch fails.

---

## POST `/api/v3.1/connected_accounts/{nanoid}/revoke`

**Endpoint:** `https://backend.composio.dev/api/v3.1/connected_accounts/{nanoid}/revoke`

**Summary:** Revoke a connected account at the provider

Best-effort upstream revocation. On success, the connection transitions to REVOKED. Returns 400 when the toolkit does not support programmatic revocation, 409 when the connection is not in a revokable state, 500 when every upstream dispatch fails.

### Authentication

**ApiKeyAuth** - API Key in `header` header `x-api-key` OR **UserApiKeyAuth** - API Key in `header` header `x-user-api-key`

### Path Parameters

- `nanoid` (string (connectedAccountId)) *(required)*: The unique identifier of the connected account

### Responses

#### 200 - Connection revoked. `revoked_tokens` reports which subjects were killed at the provider on this call; an empty array indicates the connection was already revoked.

**Response Schema:**

- `revoked_tokens` (array<enum: "access_token" | "refresh_token">) *(required)*: Tokens revoked at the provider on this call. Empty array means the connection was already revoked (no upstream dispatch).
- `connected_account` (object) *(required)*
  - `id` (string) *(required)*: The unique identifier of the connected account
  - `status` (enum: "INITIALIZING" | "INITIATED" | "ACTIVE" | ...) *(required)*: The connection status after this call (REVOKED on success).

**Example Response:**

```json
{
  "revoked_tokens": [
    "access_token"
  ],
  "connected_account": {
    "id": "string",
    "status": "INITIALIZING"
  }
}
```

#### 400 - Bad request - non-OAUTH2 auth scheme or toolkit lacks a revoke configuration.

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 401 - Unauthorized - Authentication failed

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 403 - Forbidden - Insufficient permissions to revoke this connected account

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 404 - Not found - Connected account does not exist, was deleted, or its parent auth config was removed.

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 409 - Conflict - Connection is in a state that cannot be revoked (only ACTIVE / already-REVOKED are accepted).

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 500 - Internal server error - DB failure, data integrity violation, or every upstream dispatch failed.

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

### Example cURL Request

```bash
curl -X POST "https://backend.composio.dev/api/v3.1/connected_accounts/string/revoke" \
  -H "x-api-key: YOUR_API_KEY"
```