> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openpayload.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Tombstone a device

> Retire a device while preserving a public record that it must no longer be trusted

Tombstoning marks a device as retired or compromised without erasing the fact that it once belonged to the DID.

Compatible clients should ignore a tombstoned device for new delivery and key selection. Preserving the record helps other clients recognize old device references and avoid accidentally treating a retired identifier as new.

## Tombstone or remove?

| Choice | Result |
| - | - |
| Tombstone | Keeps the device in the public record with `tombstoned: true` |
| Remove | Uses the separate `DELETE` route and removes the active entry |

For a lost or compromised device, tombstoning is generally the safer public signal.

## Request

<ParamField path="did" type="string" required>
  The DID that owns the device.
</ParamField>

<ParamField path="deviceId" type="string" required>
  The device identifier to tombstone.
</ParamField>

The body is required and carries a DID-key proof with action `tombstone_device`, the current `control_nonce`,
`valid_until`, `signer_key_id`, `canonical_payload`, and `signature`. See
[Authorize a Directory update](/guides/authorization).

<RequestExample>
  ```bash Request theme={null}
  curl --request POST \
    --url "https://directory.example.com/dids/did%3Aopenpayload%3A1111111111111111111111/devices/mobile-01/tombstone" \
    --header "Content-Type: application/json" \
    --data '{"did":"did:openpayload:1111111111111111111111","device_id":"mobile-01","action":"tombstone_device","nonce":"<control_nonce>","valid_until":"<epoch-millis>","signer_key_id":"<authorized-key-id>","canonical_payload":"<payload>","signature":"<signature>"}'
  ```
</RequestExample>

## Response

<ResponseExample>
  ```json 202 Response theme={null}
  {
    "status": "accepted",
    "did": "did:openpayload:1111111111111111111111",
    "extrinsic": "apply_control_with_proof",
    "tx_hash": "<transaction-hash>",
    "message": "Chain extrinsic submitted"
  }
  ```
</ResponseExample>

After settlement, resolve the DID and confirm that the matching device contains `"tombstoned": true`.

## Straight to the point

```http theme={null}
POST /dids/{did}/devices/{deviceId}/tombstone
```

* DID-key proof body required
* Operation: `tombstone_device`
* Accepted: `202`
* Permanent removal uses `DELETE /dids/{did}/devices/{deviceId}`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.