DISCLAIMER

The Users Onboarding API is no longer actively supported and has been deprecated, although it remains accessible online. For onboarding a new legal entity, it’s advised to reach out to the Technical office and request a VerifiableAuthorisationToOnboard. Detailed steps for this process can be found below.

Introduction

The DID Registry (DIDR) 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

info

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 timeframe, 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.

Please see DIDR API v5 specs for further information.

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 (DIDR)	Registry of DID
Trusted Policies Registry (TPR)	Registry of Smart Contract policies
Trusted Issuers Registry (TIR)	Registry for Issuers to register their accreditations
Trusted Schema Registry (TSR)	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
DIDR	didr_write	No credentials are required, but the requestor must be registered in the DID Registry	Full control over the DID Registry	insertDidDocument / updateBaseDocument / addController / revokeController / addVerificationMethod / addVerificationRelationship / revokeVerificationMethod / expireVerificationMethod / rollVerificationMethod
DIDR	didr_invite	VerifiableAuthorisationToOnboard	Registration of DID into the DID Registry	insertDidDocument: didr_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 didr_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.

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 didr_write scope from the Authorisation API v3. 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). The transaction is subsequently signed and returned to the API to broadcast the transaction across the network using the sendSignedTransaction method.

Subsequent sections of this document delve into the interactions with the DID Registry in greater detail. Comprehensive API definitions are detailed in DIDR-v5-JSONRPC API.

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

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 DIDR-v5-JSONRPC API.

info

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 (didr_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. Signed Legal Package

   This procedure involves the acknowledgement and acceptance of the Legal Package in the capacity of an Application Service Provider (ASP), and applies to the initial Pilot/Pre-Production and Production phases.

2. Project name

3. Entity name

4. DID

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

info

Please see How to issue Verifiable Credentials specification for further details.

Get didr_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 presentation definition from the AS with the desired scopes.

Steps 4 and 5:
Request didr_invite Access Token presenting the VerifiableAuthorisationToOnboard with the scope=openid didr_invite.

API CALL

The didr_invite access token must be requested by following this sequence of API calls:

• GET Presentation definition: Begin by fetching the presentation definition for the required scope.

• POST Token Endpoint: Once you have the definition, create and submit a presentation matching the fetched definition.

For further details, please consult Authorisation API guidelines

Insert DID document with the invocationCapability key

Steps 6 and 7:
Register the DID document using the insertDidDocument method with the ES256K key. 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 endpoint must be used to insert the DID document:

• DIDR JSON RPC - insertDidDocument

Steps 8:
The wallet will receive a properly formatted Ethereum transaction to be signed.

Steps 9, 10, 11 and 12:
Upon signing the transaction, it is ready for dispatch using the sendSignedTransaction method, which updates the ledger.

API CALL

The following endpoint must be used to send a signed transaction:

• DIDR JSON RPC - sendSignedTransaction

Get didr_write Access Token

Steps 13 and 14:
At this point, the user can request a didr_write Access Token with the scope=openid didr_write. Note that presentation of the VerifiableAuthorisationToOnboard is not required at this step as the DID is already onboarded.

API CALL

The didr_write access token must be requested by following this sequence of API calls:

• GET Presentation definition: Begin by fetching the presentation definition for the required scope

• POST Token Endpoint: Once you have the definition, create and submit a presentation matching the fetched definition.

For further details, please consult Authorisation API guidelines

Add verification method and verification relationships to DID document

Steps 15 and 16:
To add a verification method, you need to perform three steps:

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

API CALL

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

• DIDR JSON RPC - addVerificationMethod

• DIDR JSON RPC - addVerificationRelationship

Please note that this verification method will only appear in the DID document after adding a verification relationship.

Steps 17:
The wallet will receive an HTTP 200 transaction to be signed.

Steps 18, 19, 20 and 21:
Once the transaction is signed, it is ready to be dispatched using the method sendSignedTransaction, which updates the ledger.

API CALL

The following endpoint must be used to send a signed transaction:

• DIDR JSON RPC - sendSignedTransaction

Note: Steps 15 to 21 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

Perform actions in DID like checking a controller

Perform actions in DID like checking a controller For a detailed endpoint description, please check the documentation here:

• Perform actions in DID

JSON-RPC API

The JSON-RPC API provides methods assisting the construction of blockchain transactions and interaction with the ledger, i.e. write operation on the ledger. For a detailed endpoint description, please check the documentation here:

• JSON-RPC API