# Remove a member

> The members.remove operation: DELETE /api/v1/members/{id} in the REST API and the members_remove tool in the MCP server.

Removes one membership. The person loses the access it gave at once (their other memberships stay), and
can be invited again later. Returns the removed membership. Give a `reason`: it goes to the audit log.

You can only remove memberships you could have granted (an admin can't remove an owner), and the
organization always keeps at least one owner (`last_owner`). Needs `members:admin`; a security-tier
change.

## At a glance

- **REST:** `DELETE /api/v1/members/{id}`
- **MCP tool:** `members_remove`
- **Operation ID:** `members.remove`
- **Scope:** Organization
- **Permission:** `members:admin`
- **Risk tier:** `security`
- **Dry run:** Supported (send `Ownrecord-Dry-Run: true`)
- **Idempotency:** `Idempotency-Key` optional
- **Modes:** Test and live
- **Authentication:** API key with the `members:admin` scope
- **Since:** M1

## Request

### Path parameters

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

### Body

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

| Field    | Type   | Required | Description |
| -------- | ------ | -------- | ----------- |
| `reason` | string | No       |             |

## Response

`200 OK` with a JSON object:

| Field            | Type                                                                                                         | Description |
| ---------------- | ------------------------------------------------------------------------------------------------------------ | ----------- |
| `id`             | `mem_…` ID                                                                                                   |             |
| `object`         | `"membership"`                                                                                               |             |
| `orgId`          | `org_…` ID                                                                                                   |             |
| `userId`         | `usr_…` ID                                                                                                   |             |
| `role`           | one of `org_owner`, `org_admin`, `billing_admin`, `finance`, `tax_manager`, `support`, `developer`, `viewer` |             |
| `scope`          | object                                                                                                       |             |
| `livemodeAccess` | boolean                                                                                                      |             |
| `invitedBy`      | `usr_…` ID or null                                                                                           |             |
| `user`           | object or null                                                                                               |             |
| `createdAt`      | date-time                                                                                                    |             |
| `updatedAt`      | date-time                                                                                                    |             |

## Examples

### Remove a developer who left the team

```http
DELETE /api/v1/members/mem_01m4tx5nj8emwbyf7y9vcf47x6
Authorization: Bearer or_test_…
Content-Type: application/json

{
  "reason": "Left the company"
}
```

Response (`200`):

```json
{
  "id": "mem_01m4tx5nj8emwbyf7y9vcf47x6",
  "object": "membership",
  "orgId": "org_01m4tx5nj7ekd958x53w4bntcg",
  "userId": "usr_01m4tx5nj8emwbyf7y9vcf47xb",
  "role": "developer",
  "scope": {
    "type": "brand",
    "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4"
  },
  "livemodeAccess": false,
  "invitedBy": "usr_01m4tx5nj8emwbyf7y9vcf47xa",
  "user": {
    "email": "dev@acme.example",
    "name": "Dana Developer"
  },
  "createdAt": "2026-10-13T12:00:00.000Z",
  "updatedAt": "2026-10-13T12:00:00.000Z"
}
```

## Errors

| Code                                                                                     | HTTP status | When                                            | What to do                                                                                               |
| ---------------------------------------------------------------------------------------- | ----------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found) | 404         | No such membership in this organization.        | Check the ID and that your credentials are scoped to the right organization, entity, brand and mode.     |
| [`role_not_grantable`](https://ownrecord.io/docs/reference/errors.md#role_not_grantable) | 403         | The membership has more access than you.        | Ask an organization owner to grant this role and scope, or pick a role and scope within your own access. |
| [`last_owner`](https://ownrecord.io/docs/reference/errors.md#last_owner)                 | 409         | It's the organization's last owner.             | Make another member an owner first, then change or remove this membership.                               |
| [`version_conflict`](https://ownrecord.io/docs/reference/errors.md#version_conflict)     | 409         | The membership changed at the same time; retry. | Fetch the object again and retry the change.                                                             |
| [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied)   | 403         | You can't manage members of this organization.  | 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_reused`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_reused), [`idempotency_in_progress`](https://ownrecord.io/docs/reference/errors.md#idempotency_in_progress), [`approval_required`](https://ownrecord.io/docs/reference/errors.md#approval_required), [`approval_rejected`](https://ownrecord.io/docs/reference/errors.md#approval_rejected), [`approval_expired`](https://ownrecord.io/docs/reference/errors.md#approval_expired), [`stale_approval`](https://ownrecord.io/docs/reference/errors.md#stale_approval), [`approval_policy_denied`](https://ownrecord.io/docs/reference/errors.md#approval_policy_denied), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).