Manage a Service DID

Once registered, the umbrella DID can change its Service DIDs at any time: change their free-form fields, rotate their key, change their expiry or deactivate them.

How any change is made

Every change follows the same flow as the registration (see Register a Service DID, steps 4 to 7):

1. Request the transaction from the matching Service DID Registry API operation.
2. Save the response in unsigned-tx.json.
3. Sign it with the umbrella DID's keystore:

   did-gen sign-tx --keystore ./identity.keystore.json --tx-file unsigned-tx.json > signed.hex

4. Send it with POST /api/v1/transactions/send and {"signedRawTransaction": "<content of signed.hex>"}.
5. Check the change by resolving the Service DID.

In every operation, from is the umbrella DID's EOA.

Who can make changes

Only an account with active capability invocation on the umbrella DID. The service's own key cannot change its Service DID.

A deactivated Service DID accepts no further changes.

Change the free-form fields

POST /api/v1/contract/updateServiceDocument

{
  "serviceDid": "did:isbe:svc:uc-pre:z1MsSK9H41YvdCrJPmPycEqijYbk:3",
  "from": "0xB8172459924a1e81E511D6473f923E531f7B3a5B",

  "name": "E-invoicing service",
  "version": "2.2.0",
  "service": [
    {
      "id": "#api",
      "type": "InvoicingAPI",
      "serviceEndpoint": "https://api.facturacion.ejemplo.es/v3"
    }
  ]
}

Everything you add besides serviceDid and from makes up the new free-form fields.

Fields are replaced as a whole

The new fields replace all the previous ones: they are not merged. If you want to keep a field, include it again. To remove every free-form field, send only serviceDid and from.

The same rules as at registration apply: 4096 bytes at most and no reserved fields (see Free-form fields).

Rotate the service key

Replaces the service's signing key with another one. This is what you must do if you suspect the service key has been compromised.

1. Generate a new key:

   did-gen keys --out ./keys/facturacion-2.keystore.json

2. Request the transaction:

POST /api/v1/contract/rotateSigningKey

{
  "serviceDid": "did:isbe:svc:uc-pre:z1MsSK9H41YvdCrJPmPycEqijYbk:3",
  "newPublicKey": "0x04<new service public key>",
  "publicKeyType": "secp256k1",
  "from": "0xB8172459924a1e81E511D6473f923E531f7B3a5B"
}

The new key must follow the same rules as at registration (see The service key), and it cannot be the key the service already has.

After the rotation, the DID Document's verificationMethod shows the new key. The old one stays bound to your organisation: no service of another umbrella can ever use it.

Change the expiry

POST /api/v1/contract/updateExpiry

{
  "serviceDid": "did:isbe:svc:uc-pre:z1MsSK9H41YvdCrJPmPycEqijYbk:3",
  "newExpiresAt": 1830297600,
  "from": "0xB8172459924a1e81E511D6473f923E531f7B3a5B"
}

• newExpiresAt is the new expiry date in Unix seconds. You can work it out with epochconverter.com.
• It must be a future date, or 0 so that it never expires.
• It also works to extend the life of a service that has already expired: as long as it is not deactivated, you can give it a new date.

Deactivate a Service DID

POST /api/v1/contract/deactivateServiceDid

{
  "serviceDid": "did:isbe:svc:uc-pre:z1MsSK9H41YvdCrJPmPycEqijYbk:3",
  "from": "0xB8172459924a1e81E511D6473f923E531f7B3a5B"
}

When resolved, the DID Document will show "deactivated": true and "reason": "deactivated".

Deactivation is final

A deactivated Service DID cannot be reactivated or changed. If you need that service again later, register a new one.

Look up Service DIDs

These operations are read-only: nothing needs to be signed.

Operation	What it is for
GET /api/v1/identifiers/{serviceDid}	Resolves the service's W3C DID Document, with its free-form fields. If it is no longer valid, it includes deactivated and reason.
GET /api/v1/service-dids/{serviceDid}	Returns the service's record as stored on-chain: key, signing address, nonce, expiry, whether it is deactivated, and registration and last-update dates.
GET /api/v1/service-dids?controller={umbrella DID}	Lists all the Service DIDs of an umbrella, paginated (page and pageSize). The DID must be URL-encoded.

Common errors

In addition to those of the registration:

Error	Cause	Fix
500 — transaction execution reverted when changing a service	The service is deactivated, the new expiry is not in the future, or the new key cannot be used (it is the umbrella's key, another organisation's service key, or the key the service already has).	Check the service's state with GET /api/v1/service-dids/{serviceDid} and the data you are sending.
404 NOT_FOUND when looking it up	The Service DID does not exist in this environment.	Check the identifier and that you are using the right environment's API.