# Disconnect an OAuth client

> The oauth_connections.revoke operation: POST /api/v1/oauth_connections/{id}/revoke in the REST API and the oauth_connections_revoke tool in the MCP server.

Disconnects an OAuth client that acts for you from one organization (`orgId`), or from all of them. Its tokens
stop working there at once; once it covers no organization, every token and refresh token it holds is revoked.
Disconnecting it again changes nothing.

## At a glance

- **REST:** `POST /api/v1/oauth_connections/{id}/revoke`
- **MCP tool:** `oauth_connections_revoke`
- **Operation ID:** `oauth_connections.revoke`
- **Scope:** Platform
- **Permission:** `account:write`
- **Risk tier:** `security`
- **Dry run:** Supported (send `Ownrecord-Dry-Run: true`)
- **Idempotency:** `Idempotency-Key` required
- **Modes:** Test and live
- **Authentication:** API key with the `account:write` scope
- **Since:** M10

## Request

### Path parameters

| Field | Type       | Description |
| ----- | ---------- | ----------- |
| `id`  | `ogr_…` ID |             |

### Body

A JSON object (`Content-Type: application/json`):

| Field   | Type       | Required | Description |
| ------- | ---------- | -------- | ----------- |
| `orgId` | `org_…` ID | No       |             |

## Response

`200 OK` with a JSON object:

| Field                | Type                                                                                               | Description |
| -------------------- | -------------------------------------------------------------------------------------------------- | ----------- |
| `id`                 | string                                                                                             |             |
| `object`             | `"oauth_connection"`                                                                               |             |
| `client`             | object                                                                                             |             |
| `client.id`          | `ocl_…` ID                                                                                         |             |
| `client.name`        | string                                                                                             |             |
| `client.publisher`   | string                                                                                             |             |
| `client.dynamic`     | boolean                                                                                            |             |
| `orgs`               | array of object                                                                                    |             |
| `orgs[].orgId`       | `org_…` ID                                                                                         |             |
| `orgs[].scopes`      | array of one of 84 values, e.g. `org:read`, `org:write`, `org:admin` (all in the OpenAPI document) |             |
| `orgs[].consentedAt` | string                                                                                             |             |
| `createdAt`          | string                                                                                             |             |
| `updatedAt`          | string                                                                                             |             |

## Examples

### Disconnect from every organization

```http
POST /api/v1/oauth_connections/ogr_01m4ttwd3veh9apbewxheq5xhd/revoke
Authorization: Bearer or_test_…
Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14
```

Response (`200`):

```json
{
  "id": "ogr_01m4ttwd3veh9apbewxheq5xhd",
  "object": "oauth_connection",
  "client": {
    "id": "ocl_01m4ttwd3veh9apbewxheq5xhe",
    "name": "Claude",
    "publisher": "Unverified (registered by the client itself)",
    "dynamic": true
  },
  "orgs": [],
  "createdAt": "2026-10-25T09:00:00.000Z",
  "updatedAt": "2026-10-26T14:30:00.000Z"
}
```

## Errors

| Code                                                                                     | HTTP status | When                                          | What to do                                                                                           |
| ---------------------------------------------------------------------------------------- | ----------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found) | 404         | You have no connection with this ID.          | Check the ID and that your credentials are scoped to the right organization, entity, brand and mode. |
| [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied)   | 403         | This isn't a signed-in person in the console. | Ask an organization owner or admin for a role or scope that allows this action.                      |

It can also return these [common errors](https://ownrecord.io/docs/reference.md#common-errors): [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed), [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`invalid_json`](https://ownrecord.io/docs/reference/errors.md#invalid_json), [`unsupported_media_type`](https://ownrecord.io/docs/reference/errors.md#unsupported_media_type), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`idempotency_key_required`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_required), [`idempotency_key_reused`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_reused), [`idempotency_in_progress`](https://ownrecord.io/docs/reference/errors.md#idempotency_in_progress), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).