DID Document

Endpoints to manage the main body of the DID Document: initial registration, replacement, and field updates.

All of them return an unsigned transaction that must be signed and sent to /transactions/send.

insertFirstDidDocument

POST /api/v1/contract/insertFirstDidDocument

Creates the initial registration transaction for a DID. It is only invoked once per entity and requires the from EOA to be authorized by ISBE to perform onboarding.

Body

Field	Type	Required	Description
did	string	yes	DID generated with did-gen did.
baseDocument	string	no	JSON-string with the @context of the DID Document. If omitted, the default context is used.
vMethodId	string	yes	ID of the verification method. 32 bytes in base64url (43 chars without padding).
proof	string	yes	Proof returned by did-gen did.
publicKeyType	enum	yes	Only secp256k1 in this endpoint.
publicKey	string	yes	Uncompressed public key with 0x04 prefix.
notBefore	number	yes	Unix timestamp from which the key is valid.
notAfter	number	yes	Unix timestamp of expiration.
alsoKnownAs	string	yes	Alternative identifier (e.g., urn:oid:organizationIdentifier:...).
from	string	yes	EOA of the secp256k1 that will sign.

Example Body

{
  "did": "did:isbe:uc:z12kVar5p6bD5WCjEJcQ18Zyt8XV",
  "vMethodId": "9lfZ28jdUsYo75lVHmGNIc6oUpkjSFtxiCLjDGn28IM",
  "proof": "0x70bc9d8cdf...",
  "publicKeyType": "secp256k1",
  "publicKey": "0x041243f50ac70fc996ccc92a...",
  "notBefore": 1774602263,
  "notAfter": 2090221463,
  "alsoKnownAs": "urn:oid:organizationIdentifier:ISBE",
  "from": "0xAe0E493C67f75381b0954644836A3C16c79D0dFD"
}

Response

200 OK with the unsigned transaction (see common structure).

Errors

• 400 — Field validation.
• 500 — API or network error.

For the complete onboarding flow, see DID Onboarding.

---

insertDidDocument

POST /api/v1/contract/insertDidDocument

Replaces the DID Document of an entity that is already registered. Useful to rotate the initial control key or rewrite contexts.

Differences from insertFirstDidDocument

• Does not require alsoKnownAs in the body (it is not mandatory).
• Authorization is validated against the current controller of the DID, not against the onboarding list.

Body

Field	Type	Required	Description
did	string	yes	Existing DID.
baseDocument	string	no	New JSON-string of the @context.
vMethodId	string	yes	ID of the new verification method.
proof	string	yes	Proof of the new key.
publicKeyType	enum	yes	Only secp256k1.
publicKey	string	yes	New uncompressed public key.
notBefore	number	yes	Start timestamp.
notAfter	number	yes	End timestamp.
from	string	yes	EOA of the signing controller.

Response

200 OK with the unsigned transaction.

---

updateAlsoKnownAs

POST /api/v1/contract/updateAlsoKnownAs

Changes the value of the alsoKnownAs field of the DID Document.

Body

{
  "did": "did:isbe:uc:z12kVar5p6bD5WCjEJcQ18Zyt8XV",
  "alsoKnownAs": "urn:oid:organizationIdentifier:NEW_CODE",
  "from": "0xAe0E493C67f75381b0954644836A3C16c79D0dFD"
}

Field	Type	Required
did	string	yes
alsoKnownAs	string	yes
from	string	yes

---

updateBaseDocument

POST /api/v1/contract/updateBaseDocument

Updates the @context of the DID Document. Useful if the entity needs to add an additional JSON-LD context.

Body

{
  "did": "did:isbe:uc:z12kVar5p6bD5WCjEJcQ18Zyt8XV",
  "baseDocument": "{\"@context\":[\"https://www.w3.org/ns/did/v1\",\"https://w3id.org/security/suites/jws-2020/v1\"]}",
  "from": "0xAe0E493C67f75381b0954644836A3C16c79D0dFD"
}

Field	Type	Required
did	string	yes
baseDocument	string (serialized JSON)	yes
from	string	yes