Register DID on EBSI

How to register a DID in the DID Registry as a Legal Entity.

The DID Registry is a core EBSI service responsible for the registration, management and resolution of EBSI Decentralised Identifiers (DIDs) that utilise the did:ebsi DID method. The DID Registry enables users to engage with its smart contract to:

• Insert a DID with its default DID document
• Add or revoke DID controllers
• Add, revoke or set expiration of verification methods
• Add, revoke or set expiration of verification relationships
• Resolve a DID document at a specified time

The DID Registry maintains a chronological record. It stores DID documents, each having a specific lifecycle marked by a start and expiry time. A DID document is considered valid within this time frame, from the start to the expiry time. Key rotation introduces modifications to this timeline, altering the validity of the DID document. To determine the validity of a DID document at a particular time, the "valid-at" parameter can be utilised. If this parameter is not specified, the default value is taken as "now", implying the current point in time.

info

Consult the DID Registry API page for API instructions on how to register your DID on the DID Registry.

Mechanism

• ACTORS:

Abbreviation	Term	Description
EBSI TO	EBSI Technical Office	Technical support team within EBSI team
RTAO	Root Trusted Accreditation Organisation	Entity that issues Verifiable Accreditations for Trusted Accreditation Organisations
TAO	Trusted Accreditation Organization	Entity that issues Verifiable Accreditations (Accreditations, Attestations and Authorisations) to legal entities
TI	Trusted Issuer	Legal Entity with one or more accreditations. Accredited to accredit, attest or authorise

• REGISTRIES

Name	Role
DID Registry	Registry of DID
Policies Registry	Registry of Smart Contract policies
Issuers Registry	Registry for Issuers to register their accreditations
Schemas Registry	Registry of data schemes for data objects (e.g., VCs)

• POLICIES

API	OAuth 2.0 Scope required	Required Verifiable Credential	Granted Access	Methods to be used
DID Registry	did-registry:write	No credentials are required, but the requester must be registered in the DID Registry	Full control over the DID Registry	insertDidDocument / updateBaseDocument / addController / revokeController / addVerificationMethod / addVerificationRelationship / revokeVerificationMethod / expireVerificationMethod / rollVerificationMethod
DID Registry	did-registry:invite	VerifiableAuthorisationToOnboard	Registration of DID into the DID Registry	insertDidDocument: did-registry:invite + AT.sub == req.params.did (the DID to be inserted)

Register a DID document

After generating the DID and DID keys in line with the did:ebsi DID method, the user must receive a VerifiableAuthorisationToOnboard credential issued by an existing Trusted Issuer with a TAO role. The user must then request a Presentation Definition for the did-registry:invitescope from the EBSI Authentication API, which responds with a Verifiable Presentation and Presentation Submission. The response is sent to the /token endpoint in the Authentication API. Upon successful submission, the EBSI Authentication API issues a short-lived, OAuth 2.0 compatible access token based on the presented Verifiable Presentation. Please note, due to brief session lifetimes, which are currently defined on a case-by-case basis, refresh tokens are not supported. At this stage, the user can register the initial part of the DID document with the ES256K key, using the insertDidDocument method: the wallet fetches the DID Registry ABI, builds the corresponding calldata, and signs the resulting transaction locally before submitting it.

As EBSI requires ES256 keys for signing Verifiable Credentials, the user must add additional keys and verification relationships to complete the DID document. To do this, the user requests an access token with the did-registry:write scope from the Authorisation Service. This token is then used to perform the same steps as before but for the addVerificationMethod (to add additional keys like ES256) and addVerificationRelationship (to add authentication and assertionMethod relationships). For each of these methods, the wallet fetches the corresponding ABI, builds the calldata for the target method, signs the resulting transaction locally, and submits it to the Ledger Service using the eth_sendRawTransaction method. There is no server-side transaction-preparation call any more the wallet is responsible for building and signing every transaction itself.

Subsequent sections of this document delve into the interactions with the DID Registry in greater detail. Comprehensive API definitions are detailed in DID Registry smart contract ABI.

The diagram below captures an interaction between a client/wallet, the EBSI DID Registry Service and the Ledger Service.

Correct registration of the DID document is essential, and can be achieved by repeating the final loop step depicted in the diagram above three times, once for each of the methods specified below:

• addVerificationMethod - registers the verification method for ES256 (as depicted in the diagram above)
• addVerificationRelationship - registers the "authentication" verification relationship for ES256 key
• addVerificationRelationship - registers the "assertionMethod" verification relationship for ES256 key

All the details of the mentioned methods (and their required parameters) are available in DID Registry smart contract ABI.

important

To gain write access to the DID Registry, the user must request two separate tokens. It is important to note that these tokens cannot be requested simultaneously. Completion of the DID document baseline insertion is a prerequisite before the second token (did-registry:write) can be requested.

Create DID and DID Keys

Step 1:

Generate a DID and corresponding DID keys based on the did:ebsi DID method, utilising the ES256K and ES256 public keys. The ES256 key fulfils both authentication and assertionMethod roles, while the ES256K key is designated for capabilityInvocation.

info

EBSI offers two distinct methods for creating your DID, allowing you to tailor it to suit your specific requirements.

Please see DID Method for Legal Entities and DID Method for Natural Person specifications for further details.

Request Verifiable Authorisation To Onboard

Steps 2 and 3:
Request the VerifiableAuthorisationToOnboard credential.

In the case of RTAO, to obtain a VerifiableAuthorisationToOnboard, please contact the Support Office and provide the following information:

1. Project name
2. Entity name
3. DID

For TAOs and TIs cases, the VerifiableAuthorisationToOnboard must be issued by the Trust Chain members.

Get did-registry:invite Access Token

A Verifiable Presentation token can be used by a service to request an access token from the Authorisation Server (AS). Before invoking the token endpoint, the service must request a DCQL query from the AS with the desired scopes.

Steps 4 and 5:
Request did-registry:invite Access Token presenting the VerifiableAuthorisationToOnboard with the scope=openid did-registry:invite.

API CALL

The did-registry:invite access token must be requested by following this sequence of API calls:

• GET DCQL query: Begin by fetching the DCQL query for the required scope.

• POST Token Endpoint: Once you have the DCQL query, create and submit a presentation answering it (the vp_token is a JSON object keyed by credential-query id).

For further details, please consult Authorisation Service guidelines

Insert DID document with the invocationCapability key

Step 6:
Fetch the DID Registry ABI, build the insertDidDocument calldata from it using the ES256K key, and sign the resulting transaction locally. There is no server-side transaction-preparation call, the wallet builds and signs the transaction itself before submitting it. Submit the signed transaction to the Ledger Service with eth_sendRawTransaction. The action creates a DID document with default values and assigns the ES256K key as both the invocationCapability and authentication keys. A DID can only be claimed once; subsequent attempts will result in an exception.

The invocationCapability key must be used for future Ethereum transactions, and the authentication key must be used to sign Verifiable Presentation Tokens and ID Tokens. Note that other keys are the assertionMethod is optional, but required if the DID wants to sign Verifiable Credentials.

Executing insertDidDocument establishes a baseline for the document, employing the signature key for verificationMethod, and binding it to both authentication and invocationCapability.

API CALL

The following endpoints must be used to insert the DID document:

• DID Registry - GET abi: fetch the ABI needed to build the insertDidDocument calldata.

• Ledger Service - eth_sendRawTransaction: submit the signed transaction.

Step 7:
Upon successful submission, the Ledger Service will broadcast the transaction to the ledger. In return, you will receive the transaction hash.

You can get the receipt of the transaction by calling the eth_getTransactionReceipt method of Ledger Service.

Receipts for pending transactions are not available, therefore you will have to wait until the transaction has been processed � usually a few seconds. We recommend you to poll the eth_getTransactionReceipt method until the receipt is available.

Once the receipt is available, you can check the status field to know if the transaction succeeded (0x1) or failed (0x0). If the transaction failed, the revertReason field will give you insights about the reason for the failure. You can learn more about the format of the revert reason in Besu's documentation.

API CALL

The following endpoint must be used to check the status of the transaction:

• Ledger Service - eth_getTransactionReceipt

Get did-registry:write Access Token

Steps 8 and 9:
At this point, the user can request a did-registry:write Access Token with the scope=openid did-registry:write. Note that presentation of the VerifiableAuthorisationToOnboard is not required at this step as the DID is already onboarded.

API CALL

The did-registry:write access token must be requested by following this sequence of API calls:

• GET DCQL query: Begin by fetching the DCQL query for the required scope

• POST Token Endpoint: Once you have the DCQL query, create and submit a presentation answering it (the vp_token is a JSON object keyed by credential-query id).

For further details, please consult Authorisation Service guidelines

Add verification method and verification relationships to DID document

Step 10:
To add a verification method, you need to perform three transactions:

1. addVerificationMethod - to register the verification method for ES256
2. addVerificationRelationship - add "authentication" verification relationship for ES256 key
3. addVerificationRelationship - add "assertionMethod" verification relationship for ES256 key

For each of them, fetch the DID Registry ABI, build the corresponding calldata, sign the resulting transaction locally, and submit it to the Ledger Service with eth_sendRawTransaction there is no server-side transaction-preparation call, the wallet builds and signs each transaction itself before submitting it.

API CALL

The following endpoints must be used to add the verification methods and verification relationships:

• DID Registry - GET abi: fetch the ABI needed to build the addVerificationMethod / addVerificationRelationship calldata.

• Ledger Service - eth_sendRawTransaction: submit each signed transaction.

The verification method will only appear in the DID document after adding a verification relationship.

Step 11:
Upon successful submission, the Ledger Service will broadcast the transaction to the ledger. In return, you will receive the transaction hash.

You can get the receipt of the transaction by calling the eth_getTransactionReceipt method of Ledger Service.

Receipts for pending transactions are not available, therefore you will have to wait until the transaction has been processed � usually a few seconds. We recommend you to poll the eth_getTransactionReceipt method until the receipt is available.

Once the receipt is available, you can check the status field to know if the transaction succeeded (0x1) or failed (0x0). If the transaction failed, the revertReason field will give you insights about the reason for the failure. You can learn more about the format of the revert reason in Besu's documentation.

API CALL

The following endpoint must be used to check the status of the transaction:

• Ledger Service - eth_getTransactionReceipt

Note: Steps 10 and 11 must be executed three times, once for each of the methods mentioned, filling in their requested parameters. Bear in mind that the same verificationMethod may be applied across multiple verification relationships.

Finally, you can verify if the DID registration has been properly completed by calling the Get DID document endpoint.

DID registration example

{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/suites/jws-2020/v1"
  ],
  "id": "did:ebsi:zdctFFPeCn5nXWUDXr29SVY",
  "controller": [
    "did:ebsi:zdctFFPeCn5nXWUDXr29SVY"
  ],
  "verificationMethod": [
    {
      "id": "did:ebsi:zdctFFPeCn5nXWUDXr29SVY#Rp8YfdYz7_LnnESLd1cLj98_aC96kJx98kXcaOJkJuY",
      "type": "JsonWebKey2020",
      "controller": "did:ebsi:zdctFFPeCn5nXWUDXr29SVY",
      "publicKeyJwk": {
        "kty": "EC",
        "crv": "secp256k1",
        "x": "zC4wpPBIrTcjBSJK2QQOaN3FL4sclbTYpDZfEy4fmTc",
        "y": "mlUDPBzVRYhCLe8SB5z3WJKTjSjobSYc1CpxvsQi1zU"
      }
    },
    {
      "id": "did:ebsi:zdctFFPeCn5nXWUDXr29SVY#TfiVO_2nq5z3rRsmHYLpOLKVC1vS9Fh5fhpL4HONsTQ",
      "type": "JsonWebKey2020",
      "controller": "did:ebsi:zdctFFPeCn5nXWUDXr29SVY",
      "publicKeyJwk": {
        "kty": "EC",
        "x": "dZFz7Le3c5TwmlwXjk0SitZU6I5qkj26fLMuOYu7inw",
        "y": "yluk8rfmE0tof-krCzeBA90OxAXN1FajbMvJ4EhUyh0",
        "crv": "P-256"
      }
    }
  ],
  "authentication": [
    "did:ebsi:zdctFFPeCn5nXWUDXr29SVY#Rp8YfdYz7_LnnESLd1cLj98_aC96kJx98kXcaOJkJuY",
    "did:ebsi:zdctFFPeCn5nXWUDXr29SVY#TfiVO_2nq5z3rRsmHYLpOLKVC1vS9Fh5fhpL4HONsTQ"
  ],
  "assertionMethod": [
    "did:ebsi:zdctFFPeCn5nXWUDXr29SVY#TfiVO_2nq5z3rRsmHYLpOLKVC1vS9Fh5fhpL4HONsTQ",
    "did:ebsi:zdctFFPeCn5nXWUDXr29SVY#Rp8YfdYz7_LnnESLd1cLj98_aC96kJx98kXcaOJkJuY"
  ],
  "capabilityInvocation": [
    "did:ebsi:zdctFFPeCn5nXWUDXr29SVY#Rp8YfdYz7_LnnESLd1cLj98_aC96kJx98kXcaOJkJuY"
  ]
}

DID Registry API Endpoints

List identifiers

Returns a list of identifiers. For a detailed endpoint description, please check the documentation here:

• List identifiers

Get a DID document

Gets the DID document corresponding to the DID. For a detailed endpoint description, please check the documentation here:

• Get a DID document