Skip to main content
European CommissionEBSI European Blockchain
Get Help

Onboard

This guide presents the steps to onboard a new legal entity in EBSI, which consists in the registration of the DID Document in the DID Registry.

Setup your wallet​

Create a new DID with 2 key pairs:

  • The first key pair with the ES256K algorithm. It will be used to write data in the blockchain.
  • The second key pair with the ES256 algorithm. It will be used to sign verifiable credentials and verifiable presentations.
Command
==> using user ES256K
==> using user ES256
Output
{
  "keys": {
    "ES256K": {
      "id": "k0G8kZ0UxsxGLYiiAhRUgtLtFzu-ZpbvzFtpJIH63ZI",
      "kid": "did:ebsi:zzcJJuM4Z4AUKdL8kdMEKNw#k0G8kZ0UxsxGLYiiAhRUgtLtFzu-ZpbvzFtpJIH63ZI",
      "privateKeyJwk": {
        "kty": "EC",
        "crv": "secp256k1",
        "x": "gmT8xLpAGaGX2JnfxTnlOs5JUy7SXSQbIErwPNBbu68",
        "y": "r9JVbckK24sbIw4Nyz16qoHaAZdhNmossxyO6a_Naxo",
        "d": "O26b4UPVx_MMrzs8ibq0PCIHInEcHdouYy9mDcYcCk8"
      },
      "publicKeyJwk": {
        "kty": "EC",
        "crv": "secp256k1",
        "x": "gmT8xLpAGaGX2JnfxTnlOs5JUy7SXSQbIErwPNBbu68",
        "y": "r9JVbckK24sbIw4Nyz16qoHaAZdhNmossxyO6a_Naxo"
      },
      "privateKeyEncryptionJwk": {
        "kty": "EC",
        "crv": "secp256k1",
        "x": "gmT8xLpAGaGX2JnfxTnlOs5JUy7SXSQbIErwPNBbu68",
        "y": "r9JVbckK24sbIw4Nyz16qoHaAZdhNmossxyO6a_Naxo",
        "d": "O26b4UPVx_MMrzs8ibq0PCIHInEcHdouYy9mDcYcCk8"
      },
      "publicKeyEncryptionJwk": {
        "kty": "EC",
        "crv": "secp256k1",
        "x": "gmT8xLpAGaGX2JnfxTnlOs5JUy7SXSQbIErwPNBbu68",
        "y": "r9JVbckK24sbIw4Nyz16qoHaAZdhNmossxyO6a_Naxo"
      }
    },
    "ES256": {
      "id": "eJYROV5PYyRZxjF7QABzsd7ooTw5bFNm2Ytt6bAxySQ",
      "kid": "did:ebsi:zzcJJuM4Z4AUKdL8kdMEKNw#eJYROV5PYyRZxjF7QABzsd7ooTw5bFNm2Ytt6bAxySQ",
      "privateKeyJwk": {
        "kty": "EC",
        "crv": "P-256",
        "x": "Vm7_Vhz07e9UoblDw1rmd29bV6ykcut4npLnqhhQlVk",
        "y": "uISs1AK-TVo0duSg3AvFuBNgBPp7ex4dWmYvkFN8uRk",
        "d": "O26b4UPVx_MMrzs8ibq0PCIHInEcHdouYy9mDcYcCk8"
      },
      "publicKeyJwk": {
        "kty": "EC",
        "crv": "P-256",
        "x": "Vm7_Vhz07e9UoblDw1rmd29bV6ykcut4npLnqhhQlVk",
        "y": "uISs1AK-TVo0duSg3AvFuBNgBPp7ex4dWmYvkFN8uRk"
      },
      "privateKeyEncryptionJwk": {
        "kty": "EC",
        "x": "ORK0V91Xg9IAFAMMcl73AxXv6n2ptYKEn5nBfiKCIm4",
        "y": "yRMSUPrqVtF2-Q_HkCDYjhNcrvkJeaf9PZdY1BLs8Jc",
        "crv": "P-256",
        "d": "p4B-UL0hzwNTJFA4taL3N0a1jCmIjUMPgKiwSjO1ZjM"
      },
      "publicKeyEncryptionJwk": {
        "kty": "EC",
        "x": "ORK0V91Xg9IAFAMMcl73AxXv6n2ptYKEn5nBfiKCIm4",
        "y": "yRMSUPrqVtF2-Q_HkCDYjhNcrvkJeaf9PZdY1BLs8Jc",
        "crv": "P-256"
      }
    }
  },
  "privateKeyHex": "0x3b6e9be143d5c7f30caf3b3c89bab43c220722711c1dda2e632f660dc61c0a4f",
  "publicKeyHex": "0x048264fcc4ba4019a197d899dfc539e53ace49532ed25d241b204af03cd05bbbafafd2556dc90adb8b1b230e0dcb3d7aaa81da019761366a2cb31c8ee9afcd6b1a",
  "address": "0x8390f8b75Dfb727dD53C25a048DC4887CF482330",
  "did": "did:ebsi:zy8Psj9ez9wrsSZ7vrHE221",
  "didVersion": 1
}
caution

Save the generated private keys in a safe place

Now connect the wallet with the pilot environment and switch to the upcoming APIs:

Command
==> env pilot
==> version upcoming

Request a credential to onboard​

For this step contact with the Trusted Issuer related to your use case and request a "Verifiable Authorisation To Onboard". This veriable credential should contain your DID in the credentialSubject field. To see your DID run:

Command
==> view user.did
did:ebsi:zy8Psj9ez9wrsSZ7vrHE221
info

If there is no Trusted Issuer to contact and you are at the top level of the use case then contact with Support Office in order to get the "Verifiable Authorisation To Onboard".

Request an "invite" access token​

In this step you will request an access token to the authorisation API with the scope didr_invite. For this you have to present the authorisation to onboard obtained in the previous step:

Command
==> resAuthDIDRInvite: authorisation auth didr_invite_presentation ES256 vcToOnboard
Output - value saved in 'resAuthDIDRInvite'
{
  "access_token": "eyJhbGciOiJFUzI1NiIsImtpZCI6IldqQVB6c0RyYmtWQU0xYkhpdVh5dDlPRmdQZVRSRGpLVjNncGg1RURWUGMiLCJ0eXAiOiJKV1QifQ.eyJpYXQiOjE3MDAyMjk5MzUsImV4cCI6MTcwMDIzNzEzNSwic3ViIjoiZGlkOmVic2k6enk4UHNqOWV6OXdyc1NaN3ZySEUyMjEiLCJhdWQiOiJodHRwczovL2FwaS1waWxvdC5lYnNpLmV1L2F1dGhvcmlzYXRpb24vdjQiLCJzY3AiOiJvcGVuaWQgZGlkcl9pbnZpdGUiLCJqdGkiOiI1MGE5NzAzNi03N2Y5LTQ4ZWYtYjFmMi01ZTRiN2RkOTQ1YmQiLCJpc3MiOiJodHRwczovL2FwaS1waWxvdC5lYnNpLmV1L2F1dGhvcmlzYXRpb24vdjQifQ.uFtHY11ugcBSBVvYz3BmSPcJeoR7xNR56wuQwx6Rh_WlzUKmNepZMAsDo0bG_b8lmsmYm29gGXZiJxI5foPsEQ",
  "token_type": "Bearer",
  "expires_in": 7200,
  "scope": "openid didr_invite",
  "id_token": "eyJhbGciOiJFUzI1NiIsImtpZCI6IldqQVB6c0RyYmtWQU0xYkhpdVh5dDlPRmdQZVRSRGpLVjNncGg1RURWUGMiLCJ0eXAiOiJKV1QifQ.eyJpYXQiOjE3MDAyMjk5MzUsImV4cCI6MTcwMDIzNzEzNSwic3ViIjoiZGlkOmVic2k6enk4UHNqOWV6OXdyc1NaN3ZySEUyMjEiLCJhdWQiOiJkaWQ6ZWJzaTp6eThQc2o5ZXo5d3JzU1o3dnJIRTIyMSIsImp0aSI6Ijg4NGI1NDg2LThiNmUtNDNmNi1hMjc4LTQwNmVjYjhlNDJlZSIsIm5vbmNlIjoiZDQ2MjEwODgtMzdlYS00MzU0LTk0NDUtOGQxMDlmODI4NzhlIiwiaXNzIjoiaHR0cHM6Ly9hcGktcGlsb3QuZWJzaS5ldS9hdXRob3Jpc2F0aW9uL3Y0In0.kbm2b6Ex_OXqh7LqLY14UqQtvz8_9tX0gxVRJkLkL0S_Zv3xgyXbKxisK4hpdeWNZARbdtbY8xlWB6GoBF74bw"
}

Now load the access token:

Command
==> using token resAuthDIDRInvite.access_token

Register first part of the DID Document​

To register the first part of the DID Document run:

Command
==> did insertDidDocument

This command will interact with the DID Registry and insert the ES256K key with the relationships "authentication" and "capabilityInvocation". At this point your DID document should be like this:

Command
==> did get /identifiers/ user.did
Output
{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/suites/jws-2020/v1"
  ],
  "id": "did:ebsi:zy8Psj9ez9wrsSZ7vrHE221",
  "controller": ["did:ebsi:zy8Psj9ez9wrsSZ7vrHE221"],
  "verificationMethod": [
    {
      "id": "did:ebsi:zy8Psj9ez9wrsSZ7vrHE221#d8QNgjyF0_3DRdFnu1YwMQTlIAAb1lTEtC2568u2T64",
      "type": "JsonWebKey2020",
      "controller": "did:ebsi:zy8Psj9ez9wrsSZ7vrHE221",
      "publicKeyJwk": {
        "kty": "EC",
        "crv": "secp256k1",
        "x": "QjnMrtzeAwvgVWjEZd6lYGgMe5yvQjKvb8teLxFHf18",
        "y": "fT_D3W75TeZcJjt4eXBZtG3cfeqsVl8F6et5ClT525I"
      }
    }
  ],
  "authentication": [
    "did:ebsi:zy8Psj9ez9wrsSZ7vrHE221#d8QNgjyF0_3DRdFnu1YwMQTlIAAb1lTEtC2568u2T64"
  ],
  "capabilityInvocation": [
    "did:ebsi:zy8Psj9ez9wrsSZ7vrHE221#d8QNgjyF0_3DRdFnu1YwMQTlIAAb1lTEtC2568u2T64"
  ]
}

Request a "write" access token​

Now request an access token to the authorisation API with the scope didr_write. In this case there is no need to present the veriable authorisation to onboard because the DID is already in the registry:

Command
==> resAuthDIDRWrite: authorisation auth didr_write_presentation ES256K
Output - value saved in 'resAuthDIDRWrite'
{
  "access_token": "eyJhbGciOiJFUzI1NiIsImtpZCI6IldqQVB6c0RyYmtWQU0xYkhpdVh5dDlPRmdQZVRSRGpLVjNncGg1RURWUGMiLCJ0eXAiOiJKV1QifQ.eyJpYXQiOjE3MDAyMzE3MDgsImV4cCI6MTcwMDIzODkwOCwic3ViIjoiZGlkOmVic2k6enk4UHNqOWV6OXdyc1NaN3ZySEUyMjEiLCJhdWQiOiJodHRwczovL2FwaS1waWxvdC5lYnNpLmV1L2F1dGhvcmlzYXRpb24vdjQiLCJzY3AiOiJvcGVuaWQgZGlkcl93cml0ZSIsImp0aSI6IjkwMjJkZWFlLWU0ODEtNDk5NC04ZTM0LTc1MzNjMjNiNmQ4NyIsImlzcyI6Imh0dHBzOi8vYXBpLXBpbG90LmVic2kuZXUvYXV0aG9yaXNhdGlvbi92NCJ9.40dn2_k1Q_YQZXYLITFTwalaaQoJs987t_GjAE_irqPlE4GjhqmqhN4RPl69xaFm9IBB9eolLKSWB2dH5HuqBA",
  "token_type": "Bearer",
  "expires_in": 7200,
  "scope": "openid didr_write",
  "id_token": "eyJhbGciOiJFUzI1NiIsImtpZCI6IldqQVB6c0RyYmtWQU0xYkhpdVh5dDlPRmdQZVRSRGpLVjNncGg1RURWUGMiLCJ0eXAiOiJKV1QifQ.eyJpYXQiOjE3MDAyMzE3MDgsImV4cCI6MTcwMDIzODkwOCwic3ViIjoiZGlkOmVic2k6enk4UHNqOWV6OXdyc1NaN3ZySEUyMjEiLCJhdWQiOiJkaWQ6ZWJzaTp6eThQc2o5ZXo5d3JzU1o3dnJIRTIyMSIsImp0aSI6ImRiODIzNmQzLWI3M2MtNGQ5Ni1iNGJiLWJkZWNkZmU5MzQyMiIsIm5vbmNlIjoiMGViYjJmNjgtNGZkZi00Y2QwLWIxNmQtZjBmMDM1YzExNzUxIiwiaXNzIjoiaHR0cHM6Ly9hcGktcGlsb3QuZWJzaS5ldS9hdXRob3Jpc2F0aW9uL3Y0In0.nB0t5K0eoRqEPT1s-B6jHPMOvSb8soN3SN_Brded2O_zicjkX6uyqOlA9hNqcCZSpNQAi2rdGRdk-IwZCxxUUw"
}

Please note that the command is using the ES256K key for the authentication because this the key registered in the DID registry.

Now load the access token:

==> using token resAuthDIDRWrite.access_token

Register the second part of the DID Document​

The following steps will complete the registration of the DID Document. First register the ES256 key as verification method:

Command
==> did addVerificationMethod user.did ES256

Now create the relationship "authentication" with this verification method:

Command
==> did addVerificationRelationship user.did authentication ES256

Finally, do the same for the relationship "assertionMethod":

Command
==> did addVerificationRelationship user.did assertionMethod ES256

At this point your DID document should be like this:

Command
==> did get /identifiers/ user.did
Output
{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/suites/jws-2020/v1"
  ],
  "id": "did:ebsi:zy8Psj9ez9wrsSZ7vrHE221",
  "controller": ["did:ebsi:zy8Psj9ez9wrsSZ7vrHE221"],
  "verificationMethod": [
    {
      "id": "did:ebsi:zy8Psj9ez9wrsSZ7vrHE221#d8QNgjyF0_3DRdFnu1YwMQTlIAAb1lTEtC2568u2T64",
      "type": "JsonWebKey2020",
      "controller": "did:ebsi:zy8Psj9ez9wrsSZ7vrHE221",
      "publicKeyJwk": {
        "kty": "EC",
        "crv": "secp256k1",
        "x": "QjnMrtzeAwvgVWjEZd6lYGgMe5yvQjKvb8teLxFHf18",
        "y": "fT_D3W75TeZcJjt4eXBZtG3cfeqsVl8F6et5ClT525I"
      }
    },
    {
      "id": "did:ebsi:zy8Psj9ez9wrsSZ7vrHE221#-gIhC6LBcLhgP2mUhLc7uJoG-6Fd7WxRTxanIYBk12o",
      "type": "JsonWebKey2020",
      "controller": "did:ebsi:zy8Psj9ez9wrsSZ7vrHE221",
      "publicKeyJwk": {
        "kty": "EC",
        "crv": "P-256",
        "x": "Cbe06PxqDBf6t1t4Eyk4va7TjPPq7TqmtJdT53L3Amw",
        "y": "A6ChunbYIgvAZVKuN15slVtFq1jfReRqDDbwBW9uViI"
      }
    }
  ],
  "authentication": [
    "did:ebsi:zy8Psj9ez9wrsSZ7vrHE221#d8QNgjyF0_3DRdFnu1YwMQTlIAAb1lTEtC2568u2T64",
    "did:ebsi:zy8Psj9ez9wrsSZ7vrHE221#-gIhC6LBcLhgP2mUhLc7uJoG-6Fd7WxRTxanIYBk12o"
  ],
  "assertionMethod": [
    "did:ebsi:zy8Psj9ez9wrsSZ7vrHE221#-gIhC6LBcLhgP2mUhLc7uJoG-6Fd7WxRTxanIYBk12o"
  ],
  "capabilityInvocation": [
    "did:ebsi:zy8Psj9ez9wrsSZ7vrHE221#d8QNgjyF0_3DRdFnu1YwMQTlIAAb1lTEtC2568u2T64"
  ]
}
Congratulations!

You have registered a new Legal Entity in the DID Registry

The CLI tool is equipped with a script to simplify the process of registering a new Legal Entity. First, setup your wallet and request a verifiable authorisation to onboard. Then run:

Command
==> run registerDidDocument_ES256K_ES256 vcToOnboard