---
title: "Replace a DID"
method: PUT
path: "/identifiers/{did}"
tags: ["Dids"]
---

# Replace a DID

`PUT /identifiers/{did}`

Replaces the mutable declarative fields of a DID in one request.
Collections in the body are full replacement sets. Verification
methods and key mappings are intentionally managed through their
dedicated sub-resource endpoints.

## Parameters

- `./common-components.yml#/components/parameters/CorrelationId` — unresolved $ref

## Request body

- DidReplaceRequest — Request body for fully replacing a DID's mutable declarative fields. Collection fields are replacement sets. Verification methods and key mappings are excluded and must be managed through their sub-resource endpoints.
  - `alias` string, nullable
  - `canonicalId` string, nullable
  - `controllers` string[] — Full replacement set of controller DID strings.
  - `alsoKnownAs` string[] — Full replacement set of also-known-as URIs.
  - `equivalentIds` string[] — Full replacement set of equivalent DID strings.
  - `contexts` string[] — Full replacement set of DID document context URIs.
  - `deactivated` boolean, nullable — Optional DID document deactivated flag to store with the replacement.
  - `services` DidDocumentService[] — Full replacement set of DID service entries. — unresolved $ref
  - `relationships` object[] — Full replacement set of relationship entries.
    - `purpose` string, required — Verification purpose.
    - `verificationMethodId` string, nullable — Existing local verification method id to reference.
    - `referenceDidUrl` string, nullable — External DID URL reference. Mutually exclusive with `verificationMethodId`.

## Response `200`

DID replaced successfully.

- Did — unresolved $ref

## Other responses

- `400` — unresolved $ref
- `401` — unresolved $ref
- `403` — unresolved $ref
- `404` — unresolved $ref
- `500` — unresolved $ref

## Changes

- **2026-06-26** `a1581f6b71f3` — 4 info
  - added the new optional request property `contexts`
  - added the new optional request property `deactivated`
  - added the new optional request property `relationships`
  - added the new optional request property `services`

[Change history](https://skmtc.dev/sphereon-opensource/apis/did-rest-api/changes/identifiers/:did/put.md)

---

[API](https://skmtc.dev/sphereon-opensource/apis/did-rest-api.md) · [All operations](https://skmtc.dev/sphereon-opensource/apis/did-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/sphereon-opensource/did-rest-api/revisions/d575fc307e80/schema)