Skip to main content

Update DID Documents

You can extend DID Documents by adding verification methods, services and custom properties. A verification method adds public keys, which can be used to digitally sign things like a DID message or a verifiable credential, while a service can provide metadata around the identity via URIs.

Verification Methods​

As demonstrated by the example below, the IOTA Identity library offers easy-to-use methods for adding verification methods.

Properties​

You can specify the following properties for a verification method:

  • id: A DID URL for the verification method. You can specify it by setting the fragment.
  • type: Specifies the type of the verification method. The library supports Ed25519 and X25519 key types. This property is automatically filled by the library when specifying the verification material.
  • publicKeyMultibase: A multi-base encoded public key which concludes the verification material. This can be automatically generated by the library or manually provided by users.

Verification Relationships​

Verification relationships express the relationship between the DID subject and the verification method. You can use it to specify the purpose of the verification method.

Relationships​

The Identity Library supports the following relationships:

Verification methods can be either embedded or referenced. Referencing verification methods allows them to be used by more than one verification relationship. When you create a verification method using the Identity library, specifying the MethodScope option will result in an embedded verification method. Leaving that option unset will create the verification method as a map entry of the verificationMethod property. You can also add verification relationships afterward using references.

note

Updates to the DID Document are done through the invocation of Identity::execute_update API by an Identity's controller. The public key or address of the controller does not need to be a verification method in the DID Document, since the controller is authenticated through possession of a ControllerCap token.

Services​

Services allow you to add other ways of communicating with the DID subject. An endpoint included in the DID Document can offer a way of reaching services for different purposes like authentication, communicating, and discovery.

Properties​

You can specify the following properties for a service:

  • id: A DID URL for referencing the service in the DID document. You can specify it by setting the fragment.
  • type: A string used to maximize interoperability between services. The library does not perform any checks on the content of this string.
  • serviceEndpoint: A URL that points to the service endpoint.

Create Identity​

Before you can update anything, you will need to create an Identity.

examples/0_basic/1_update_did.rs
loading...

This creates and publishes an Identity object containing a DID Document with one verification method.

{
  "doc": {
    "id": "did:iota:aa8c860b:0x38469f7a226cc62446452841c19a10971b04bc1d718cd808d61363caceb6988a",
    "verificationMethod": [
      {
        "id": "did:iota:aa8c860b:0x38469f7a226cc62446452841c19a10971b04bc1d718cd808d61363caceb6988a#RqsnXWDY536aFs-8ZzuxcUFYmjG4whZzt3glj7YTi_g",
        "controller": "did:iota:aa8c860b:0x38469f7a226cc62446452841c19a10971b04bc1d718cd808d61363caceb6988a",
        "type": "JsonWebKey2020",
        "publicKeyJwk": {
          "kty": "OKP",
          "alg": "EdDSA",
          "kid": "RqsnXWDY536aFs-8ZzuxcUFYmjG4whZzt3glj7YTi_g",
          "crv": "Ed25519",
          "x": "OJ1vnsXh8Hm69iPmTMlxKpndfKmcGRZXhWKt-dFB488"
        }
      }
    ]
  },
  "meta": {
    "created": "2025-03-11T10:01:28Z",
    "updated": "2025-03-11T10:01:28Z"
  }
}

Add a Verification Method​

examples/0_basic/1_update_did.rs
loading...

This creates a new verification method that includes a newly generated Ed25519 public key.

{
  "doc": {
    "id": "did:iota:aa8c860b:0x38469f7a226cc62446452841c19a10971b04bc1d718cd808d61363caceb6988a",
    "verificationMethod": [
      {
        "id": "did:iota:aa8c860b:0x38469f7a226cc62446452841c19a10971b04bc1d718cd808d61363caceb6988a#RqsnXWDY536aFs-8ZzuxcUFYmjG4whZzt3glj7YTi_g",
        "controller": "did:iota:aa8c860b:0x38469f7a226cc62446452841c19a10971b04bc1d718cd808d61363caceb6988a",
        "type": "JsonWebKey2020",
        "publicKeyJwk": {
          "kty": "OKP",
          "alg": "EdDSA",
          "kid": "RqsnXWDY536aFs-8ZzuxcUFYmjG4whZzt3glj7YTi_g",
          "crv": "Ed25519",
          "x": "OJ1vnsXh8Hm69iPmTMlxKpndfKmcGRZXhWKt-dFB488"
        }
      },
      {
        "id": "did:iota:aa8c860b:0x38469f7a226cc62446452841c19a10971b04bc1d718cd808d61363caceb6988a#N4dDJyf6fi83gP42llhd8qSV5ajHCIH4cfWxpPEFeYw",
        "controller": "did:iota:aa8c860b:0x38469f7a226cc62446452841c19a10971b04bc1d718cd808d61363caceb6988a",
        "type": "JsonWebKey2020",
        "publicKeyJwk": {
          "kty": "OKP",
          "alg": "EdDSA",
          "kid": "N4dDJyf6fi83gP42llhd8qSV5ajHCIH4cfWxpPEFeYw",
          "crv": "Ed25519",
          "x": "EO6qiaEQgV33XzMGU86eeSBp6Y52i10Tg-VWWsj986Q"
        }
      }
    ]
  },
  "meta": {
    "created": "2025-03-11T10:01:28Z",
    "updated": "2025-03-11T10:01:28Z"
  }
}

Add Verification Relationships​

You can attach verification relationships to a verification method by referencing its fragment.

examples/0_basic/1_update_did.rs
loading...

This will add Authentication relationship to the verification method with the fragment key-1. Note that Authentication references the already included key-2 verification method:

{
  "doc": {
    "id": "did:iota:aa8c860b:0x38469f7a226cc62446452841c19a10971b04bc1d718cd808d61363caceb6988a",
    "verificationMethod": [
      {
        "id": "did:iota:aa8c860b:0x38469f7a226cc62446452841c19a10971b04bc1d718cd808d61363caceb6988a#RqsnXWDY536aFs-8ZzuxcUFYmjG4whZzt3glj7YTi_g",
        "controller": "did:iota:aa8c860b:0x38469f7a226cc62446452841c19a10971b04bc1d718cd808d61363caceb6988a",
        "type": "JsonWebKey2020",
        "publicKeyJwk": {
          "kty": "OKP",
          "alg": "EdDSA",
          "kid": "RqsnXWDY536aFs-8ZzuxcUFYmjG4whZzt3glj7YTi_g",
          "crv": "Ed25519",
          "x": "OJ1vnsXh8Hm69iPmTMlxKpndfKmcGRZXhWKt-dFB488"
        }
      },
      {
        "id": "did:iota:aa8c860b:0x38469f7a226cc62446452841c19a10971b04bc1d718cd808d61363caceb6988a#N4dDJyf6fi83gP42llhd8qSV5ajHCIH4cfWxpPEFeYw",
        "controller": "did:iota:aa8c860b:0x38469f7a226cc62446452841c19a10971b04bc1d718cd808d61363caceb6988a",
        "type": "JsonWebKey2020",
        "publicKeyJwk": {
          "kty": "OKP",
          "alg": "EdDSA",
          "kid": "N4dDJyf6fi83gP42llhd8qSV5ajHCIH4cfWxpPEFeYw",
          "crv": "Ed25519",
          "x": "EO6qiaEQgV33XzMGU86eeSBp6Y52i10Tg-VWWsj986Q"
        }
      }
    ],
    "authentication": [
      "did:iota:aa8c860b:0x38469f7a226cc62446452841c19a10971b04bc1d718cd808d61363caceb6988a#N4dDJyf6fi83gP42llhd8qSV5ajHCIH4cfWxpPEFeYw"
    ]
  },
  "meta": {
    "created": "2025-03-11T10:01:28Z",
    "updated": "2025-03-11T10:01:28Z"
  }
}

Add a Service​

You can also add custom properties can to a service by setting properties:

examples/0_basic/1_update_did.rs
loading...

The updated Document with the newly created service looks as follows.

{
  "doc": {
    "id": "did:iota:aa8c860b:0x38469f7a226cc62446452841c19a10971b04bc1d718cd808d61363caceb6988a",
    "verificationMethod": [
      {
        "id": "did:iota:aa8c860b:0x38469f7a226cc62446452841c19a10971b04bc1d718cd808d61363caceb6988a#RqsnXWDY536aFs-8ZzuxcUFYmjG4whZzt3glj7YTi_g",
        "controller": "did:iota:aa8c860b:0x38469f7a226cc62446452841c19a10971b04bc1d718cd808d61363caceb6988a",
        "type": "JsonWebKey2020",
        "publicKeyJwk": {
          "kty": "OKP",
          "alg": "EdDSA",
          "kid": "RqsnXWDY536aFs-8ZzuxcUFYmjG4whZzt3glj7YTi_g",
          "crv": "Ed25519",
          "x": "OJ1vnsXh8Hm69iPmTMlxKpndfKmcGRZXhWKt-dFB488"
        }
      },
      {
        "id": "did:iota:aa8c860b:0x38469f7a226cc62446452841c19a10971b04bc1d718cd808d61363caceb6988a#N4dDJyf6fi83gP42llhd8qSV5ajHCIH4cfWxpPEFeYw",
        "controller": "did:iota:aa8c860b:0x38469f7a226cc62446452841c19a10971b04bc1d718cd808d61363caceb6988a",
        "type": "JsonWebKey2020",
        "publicKeyJwk": {
          "kty": "OKP",
          "alg": "EdDSA",
          "kid": "N4dDJyf6fi83gP42llhd8qSV5ajHCIH4cfWxpPEFeYw",
          "crv": "Ed25519",
          "x": "EO6qiaEQgV33XzMGU86eeSBp6Y52i10Tg-VWWsj986Q"
        }
      }
    ],
    "authentication": [
      "did:iota:aa8c860b:0x38469f7a226cc62446452841c19a10971b04bc1d718cd808d61363caceb6988a#N4dDJyf6fi83gP42llhd8qSV5ajHCIH4cfWxpPEFeYw"
    ],
    "service": [
      {
        "id": "did:iota:aa8c860b:0x38469f7a226cc62446452841c19a10971b04bc1d718cd808d61363caceb6988a#linked-domain",
        "type": "LinkedDomains",
        "serviceEndpoint": "https://iota.org/"
      }
    ]
  },
  "meta": {
    "created": "2025-03-11T10:01:28Z",
    "updated": "2025-03-11T10:01:28Z"
  }
}

Remove a Verification Method​

You can also remove verification methods at any time using the following snippet:

examples/0_basic/1_update_did.rs
loading...

This removes the original verification method.

{
  "doc": {
    "id": "did:iota:aa8c860b:0x38469f7a226cc62446452841c19a10971b04bc1d718cd808d61363caceb6988a",
    "verificationMethod": [
      {
        "id": "did:iota:aa8c860b:0x38469f7a226cc62446452841c19a10971b04bc1d718cd808d61363caceb6988a#N4dDJyf6fi83gP42llhd8qSV5ajHCIH4cfWxpPEFeYw",
        "controller": "did:iota:aa8c860b:0x38469f7a226cc62446452841c19a10971b04bc1d718cd808d61363caceb6988a",
        "type": "JsonWebKey2020",
        "publicKeyJwk": {
          "kty": "OKP",
          "alg": "EdDSA",
          "kid": "N4dDJyf6fi83gP42llhd8qSV5ajHCIH4cfWxpPEFeYw",
          "crv": "Ed25519",
          "x": "EO6qiaEQgV33XzMGU86eeSBp6Y52i10Tg-VWWsj986Q"
        }
      }
    ],
    "authentication": [
      "did:iota:aa8c860b:0x38469f7a226cc62446452841c19a10971b04bc1d718cd808d61363caceb6988a#N4dDJyf6fi83gP42llhd8qSV5ajHCIH4cfWxpPEFeYw"
    ],
    "service": [
      {
        "id": "did:iota:aa8c860b:0x38469f7a226cc62446452841c19a10971b04bc1d718cd808d61363caceb6988a#linked-domain",
        "type": "LinkedDomains",
        "serviceEndpoint": "https://iota.org/"
      }
    ]
  },
  "meta": {
    "created": "2025-03-11T10:01:28Z",
    "updated": "2025-03-11T10:01:28Z"
  }
}

Full Example Code​

examples/0_basic/1_update_did.rs
loading...