Rotating an assertion key

Edit online

An issuer can rotate an assertion key while retaining the previous key. Use the following PATCH endpoint to rotate an assertion key. 
PATCH /v2.0/credential_definitions/{id}{
 "op": ”key_rollover”
}
Response (updated DID Document of the agent): 
{
     …
     "verificationMethod": [
         "id": "did:web:diagency%3A9720:diagency:dids:v1.0:b342243b-90b7-42bc-9e7c-
          5fde7edf28a0#GbFMwUUW4VDAzz84nYLuhj2WBDLDC97yTos29dm6PV8C",
         "type": "Ed25519VerificationKey2020",
         "controller": "did:web:diagency%3A9720:diagency:dids:v1.0:b342243b-90b7-
          42bc-9e7c-5fde7edf28a0",
         "deprecated": false,
         "publicKeyMultibase": "z6MkrksFdZoqfJnMeUZJ9rWo36Q9XKgD5axrruria5bTiQUQ”
     ],
     …
}

The key that is shown in the response is added to the DID document of the agent, along with the previous key. The deprecated state of the previous key is set to true. The state flag deprecated is used to identify the rotated-out keys (deprecated = true) and current keys (deprecated = false).

When performing rollover on a mso_mdoc formatted credential definition, a new X509 certificate contains the new keypair. If you are managing your own custom keys and certificates for mdoc, then you can perform a rollover and specify the new key and certificate as follows: 
PATCH /v2.0/credential_definitions/{id}
{
    "op": ”key_rollover” ,
    "mso_mdoc": {
        "custom_cert_key_pair": {
            "certificate": " -----BEGIN CERTIFICATE-----\n……",
            "private_key": " -----BEGIN PRIVATE KEY-----\n……"
        }
    },
}
Response (updated DID Document of the agent): 
{
     …
     "verificationMethod": [
         "id": "did:web:diagency%3A9720:diagency:dids:v1.0:b342243b-90b7-42bc-9e7c-
          5fde7edf28a0#GbFMwUUW4VDAzz84nYLuhj2WBDLDC97yTos29dm6PV8C",
         "type": "Ed25519VerificationKey2020",
         "controller": "did:web:diagency%3A9720:diagency:dids:v1.0:b342243b-90b7-
          42bc-9e7c-5fde7edf28a0",
         "deprecated": false,
         "publicKeyMultibase": "z6MkrksFdZoqfJnMeUZJ9rWo36Q9XKgD5axrruria5bTiQUQ”
     ],
     …
}

Removing deprecated assertion keys

Note: Only the keys which have a deprecated state of true can be removed.
The owning issuer agent can inspect the DID document and remove the deprecated keys by using the following PATCH endpoint. 
PATCH /v2.0/credential_definitions/{id}
{
     "op": "key_remove"
     "id": "did:web:diagency%3A9720:diagency:dids:v1.0:b342243b-90b7-42bc-
      9e7c-5fde7edf28a0#z6MkfBMxLbwuEruPpz4JGj5m1LAxScteSkD4tYP6cr8w7Pis"
}
Response
{
     < agent DID document with removed key >
}

The assertion key with the specified id is removed from the DID document of the agent.

Displaying deprecated assertion keys

The following GET credential definitions API endpoint returns the assertion key ids that are associated with a credential definition. 
GET /v2.0/credential_definitions/{id}
Response (updated DID Document of the agent):
{
     …
     "signing_key_id": "did:web:diagency%3A9720:diagency:dids:v1.0:b342243b-90b7-
      42bc-9e7c-5fde7edf28a0#GbFMwUUW4VDAzz84nYLuhj2WBDLDC97yTos29dm6PV8C",
     "deprecated_signing_key_ids": [ 
          "did:web:diagency%3A9720:diagency:dids:v1.0:b342243b-90b7-42bc-9e7c-
           5fde7edf28a0#z6MkpZkp3frMgcNcG9s6CCgitidxFFWnCCCSDrMZeCjucK98",
          "did:web:diagency%3A9720:diagency:dids:v1.0:b342243b-90b7-42bc-9e7c-
           5fde7edf28a0#z6MkfBMxLbwuEruPpz4JGj5m1LAxScteSkD4tYP6cr8w7Pis",
     ],
     …
}