# Delete your account

URL: https://heaven.dev/docs/reference/account/delete
Updated: 2026-11-21

Delete your account and leave your organizations. The first call requests an email verification code. Give the code to confirm deletion, then read the returned operation to follow it. Your Computers in organizations with other members transfer to the selected member or organization. Your payment methods stop paying for organizations where you are billing owner, and another member is offered billing ownership. Organizations with no remaining members close and their resources are deleted.

`POST /v1/account/delete`

## Parameters

- `transfer_computers_to` (object)
  - `user` (string, required): Email address or user ID of the member to receive your Computers. Ownership goes to the organization by default.
- `code` (string): Verification code sent to your sign-in email address. Treated as a secret and never included in errors.

## Returns

- `data` (object, always present): A deletion preview and confirmation deadline, or an accepted deletion operation group.
  - `alternative-1` (object): The effects of deleting your account and the confirmation required to proceed.
    - `addresses` (string[] | null, always present): Your personal static addresses to be released.
    - `balance_micros` (integer, always present): Wallet balance forfeited without refund, in millionths of a US dollar.
    - `capacity` (string[] | null, always present): Your personal capacity purchases to be released.
    - `code_expires_at` (string (date-time), always present): When the confirmation code expires.
    - `code_sent_to` (string, always present): Email address receiving the deletion confirmation code.
    - `computers` (string[] | null, always present): Your personal Computers to be deleted.
    - `organizations` (object[] | null, always present): Organizations you leave or close, and who receives your Computers there.
      - `items` (object): How deleting your account affects one organization.
        - `addresses` (string[]): Static addresses released when the organization closes. May be omitted.
        - `billing_owner` (boolean, always present): Whether you are this organization's billing owner.
        - `closes` (boolean, always present): Whether the organization closes because you are its last member.
        - `computers` (string[] | null, always present): Computers you own in this organization.
        - `computers_to` (string, always present): Who receives those Computers. Empty when the organization closes and they are deleted.
        - `id` (string, always present): Organization ID.
        - `name` (string, always present): Organization name.
        - `pools` (string[]): Pools removed when the organization closes. May be omitted.
    - `pools` (string[] | null, always present): Your personal pools to be deleted.
  - `alternative-2` (object): The current state of a grouped change.
    - `operation` (object, always present): Group and the operations or steps that determine its outcome.
      - `completed_at` (string (date-time)): When the group finished. Absent while unfinished. May be omitted.
      - `created_at` (string (date-time), always present): When the grouped change was accepted.
      - `id` (string, always present): Group ID for `operation view`.
      - `kind` (string, always present): Grouped change.
      - `message` (string): An explanation of the group's progress or failure. May be omitted.
      - `operations` (object[] | null, always present): Member Computer operations.
        - `items` (object): An accepted change to one Computer. Work continues after the request disconnects.
          - `by` (string): Requester's email address, or user ID if no email is recorded. Omitted for your own requests. May be omitted.
          - `completed_at` (string (date-time)): When the operation reached its final state. Absent while unfinished. May be omitted.
          - `computer_id` (string, always present): Computer's stable ID.
          - `created_at` (string (date-time)): When Heaven accepted the change. May be omitted.
          - `error_code` (string): Recorded failure code. May be omitted.
          - `id` (string, always present): Operation ID for `operation view`.
          - `kind` (string, always present): Change being tracked.
          - `message` (string): An explanation of the recorded failure and any next action. May be omitted.
          - `state` (string, always present): `accepted` means saved and unfinished. `complete` means the change finished. `failed` means it could not finish. `superseded` means a newer change replaced it before completion. Values: `"accepted"`, `"complete"`, `"failed"`, `"superseded"`.
      - `pool_id` (string): Pool this change concerns. May be omitted.
      - `state` (string, always present): `accepted` while work remains, `complete` when all work succeeds, or `failed` when a step fails or a member operation fails or is superseded. Values: `"accepted"`, `"complete"`, `"failed"`, `"superseded"`.
      - `steps` (object[]): Other steps, in execution order. May be omitted.
        - `items` (object): A step in a grouped change outside its Computer operations.
          - `kind` (string, always present): Action taken by this step.
          - `message` (string): Progress or failure details for this step. May be omitted.
          - `pool_id` (string): Affected pool's ID. May be omitted.
          - `state` (string, always present): Step's recorded progress or outcome.
          - `subject` (string): Affected object, such as an organization being left. May be omitted.
      - `subject` (string): Other object the change concerns, such as a pool snapshot's name. May be omitted.

## Errors

Each code is explained in full at https://heaven.dev/docs/reference/errors.

| Code | Status | What happened |
|---|---:|---|
| `invalid` | 400 | An input is missing or invalid. |
| `unauthenticated` | 401 | The credential is missing, invalid, expired or revoked. |
| `denied` | 403 | The caller lacks permission for this action. |
| `not_found` | 404 | The resource is absent or inaccessible to this caller. |
| `conflict` | 409 | The request conflicts with the current resource state or an earlier request. |
| `over_capacity` | 409 | The request exceeds a resource or credential allowance. |
| `access_list_full` | 409 | The change would exceed the access-list allowance. |
| `payment_required` | 402 | Payment or credit is required. |
| `rate_limited` | 429 | The caller's request rate exceeds its limit. |
| `busy` | 429 | Too much work is in progress to accept this request. |
| `unknown` | 503 | The outcome is unconfirmed; a change may have happened. |
| `unavailable` | 503 | The service or requested feature is unavailable. |

## Notes

- CLI: `heaven login` with `HEAVEN_API_KEY` unset. MCP: Heaven sign-in. cURL: `HEAVEN_SIGN_IN_KEY` from approved device sign-in (`POST /v1/auth/create`).
- A key limited to a command list cannot run this command.
- **Send the code:** Email a verification code and preview account deletion. Optional: `transfer_computers_to`.
- **Delete:** Confirm account deletion with the emailed verification code. Required: `code`. Optional: `transfer_computers_to`.

## Examples

```sh tab="heaven CLI"
heaven account delete
  [--transfer-computers-to USER]
  [--code CODE]
```

```sh tab="SSH"
ssh cli@heaven.dev account delete
  [--transfer-computers-to USER]
  [--code CODE]
```

```sh tab="cURL"
curl https://heaven.dev/v1/account/delete \
  -H "Authorization: Bearer $HEAVEN_SIGN_IN_KEY" \
  --json '{}'
```

```json tab="MCP"
{ "tool": "account_delete",
  "arguments": {  } }
```

Response:

```json title="Response excerpt"
{
  "version": 1,
  "data": {
    "addresses": [],
    "balance_micros": 1010000000,
    "capacity": [
      "cap-d1edd6d6ca51b323"
    ],
    "code_expires_at": "2026-11-16T12:15:00Z",
    "code_sent_to": "you@example.com",
    "computers": [
      "my-api",
      "my-site"
    ],
    "organizations": [
      {
        "billing_owner": true,
        "closes": true,
        "computers": [
          "my-api",
          "my-site"
        ],
        "computers_to": "",
        "id": "5f763cb4-b7a4-458d-a3bf-cd4905546923",
        "name": "acme",
        "pools": [
          "web"
        ]
      }
    ],
    "pools": [
      "web"
    ]
  }
}
```
