Introduction
To insert transactions into the underlying blockchain, a Legal Entity must have a valid Verifiable Credential (VC) for the specified purpose and request an access token with the appropriate scope.
Scope definitions
To help understand the context and requirements for each scope used in the process, the following table provides a detailed explanation of the scopes.
| Scope | Required Verifiable Credential | Granted Access |
|---|---|---|
| didr_invite | VerifiableAuthorisationToOnboard | Can register DID into DID Registry |
| tir_invite | VerifiableAuthorisationForTrustChain or VerifiableAccreditationToAttest or VerifiableAccreditationToAccredit | Can register VC into Trusted Issuers Registry |
| didr_write tir_write | No credentials are required, but the client must be a Trusted Issuer. | Can fully manipulate DID Registry and Trusted Issuers Registry |
Sequence diagram
Step-by-step guide
1. Query presentation definition requirements
To start, query the Presentation definitions endpoint to get the requirements for the vp_token.
This endpoint can list all possible definitions or select one with the desired scope. Use the query parameter scope with a space-separated list of values.
Presentation definition query example
GET https://api-conformance.ebsi.eu/authorisation/v3/presentation-definitions?scope=openid+didr_invite
{
id: 'didr_invite_presentation',
input_descriptors: [
{
id: 'didr_invite_credential',
name: 'Accreditation to write to the DID Registry',
purpose: 'Please present a valid VerifiableAuthorisationToOnboard issued by Root TAO or TAO',
format: { jwt_vc: { alg: [ 'ES256' ] } },
constraints: {
fields: [
{
path: [ '$.vc.type' ],
filter: {
type: 'array',
contains: { const: 'VerifiableAuthorisationToOnboard' }
}
}
]
}
}
],
format: { jwt_vc: { alg: [ 'ES256' ] }, jwt_vp: { alg: [ 'ES256' ] } }
}
2. Request token
After handling the Presentation Definition requirements, form a Verifiable Presentation (VP) Token with Presentation Submission and send it to the Token Endpoint with grant_type=vp_token and the requested scopes. The response will include an Access Token, which can be used with EBSI Services.
Token request example
HTTP POST into: https://api-conformance.ebsi.eu/conformance/v3/auth-mock/token
grant_type=vp_token
&scope=openid+didr_invite
&vp_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6ImRpZDplYnNpOnpkUGoxR1BYamZFUlh4WFBFMVlUWWRKIzdqM1RwYU5kUE5UT3pPdG91T09rbmxPTFFrM0pQLXlrVGZyYVd0WTNHTUUifQ.eyJpc3MiOiJkaWQ6ZWJzaTp6ZFBqMUdQWGpmRVJYeFhQRTFZVFlkSiIsImF1ZCI6Imh0dHBzOi8vYXBpLWNvbmZvcm1hbmNlLmVic2kuZXUvY29uZm9ybWFuY2UvdjMvYXV0aC1tb2NrIiwic3ViIjoiZGlkOmVic2k6emRQajFHUFhqZkVSWHhYUEUxWVRZZEoiLCJpYXQiOjE1ODk2OTkyNjAsIm5iZiI6MTU4OTY5OTI2MCwiZXhwIjoxNTg5Njk5MjYwLCJub25jZSI6InhqZk9VTmY1OWFzZm4yM2ZOazEyM2tmbHNEIiwianRpIjoidXJuOnV1aWQ6MDcwNjA2MWEtZTJjYS00NjE0LTlkZTctOWMxNDUxOTM1ZjAyIiwidnAiOnsiQGNvbnRleHQiOlsiaHR0cHM6Ly93d3cudzMub3JnLzIwMTgvY3JlZGVudGlhbHMvdjEiXSwiaWQiOiJ1cm46dXVpZDowNzA2MDYxYS1lMmNhLTQ2MTQtOWRlNy05YzE0NTE5MzVmMDIiLCJ0eXBlIjpbIlZlcmlmaWFibGVQcmVzZW50YXRpb24iXSwiaG9sZGVyIjoiZGlkOmVic2k6emRQajFHUFhqZkVSWHhYUEUxWVRZZEoiLCJ2ZXJpZmlhYmxlQ3JlZGVudGlhbCI6WyJleUowZVhBaU9pSktWMVFpTENKaGJHY2lPaUpGVXpJMU5pSXNJbXRwWkNJNkltUnBaRHBsWW5OcE9ucDJTRmRZTXpVNVFUTkRkbVpLYmtOWllVRnBRV1JsSTBZd2NqVlBlWFJmYkdGb2RuWjZOazFYYkZsek0yMWpXVTVMV21scFVXUlZabkYyT0hSemFFaE9PWGNpZlEuZXlKcGMzTWlPaUprYVdRNlpXSnphVHA2ZGtoWFdETTFPVUV6UTNabVNtNURXV0ZCYVVGa1pTSXNJbk4xWWlJNkltUnBaRHBsWW5OcE9ucGtVR294UjFCWWFtWkZVbGg0V0ZCRk1WbFVXV1JLSWl3aWFXRjBJam94TlRnNU5qazVNall3TENKdVltWWlPakUxT0RrMk9Ua3lOakFzSW1WNGNDSTZNVFU0T1RZNU9USTJNQ3dpYW5ScElqb2lkWEp1T25WMWFXUjFibVJsWm1sdVpXUWlMQ0oyWXlJNmV5SkFZMjl1ZEdWNGRDSTZXeUpvZEhSd2N6b3ZMM2QzZHk1M015NXZjbWN2TWpBeE9DOWpjbVZrWlc1MGFXRnNjeTkyTVNKZExDSnBaQ0k2SW5WeWJqcDFkV2xrT25WdVpHVm1hVzVsWkNJc0luUjVjR1VpT2xzaVZtVnlhV1pwWVdKc1pVTnlaV1JsYm5ScFlXd2lMQ0pXWlhKcFptbGhZbXhsUVhSMFpYTjBZWFJwYjI0aUxDSldaWEpwWm1saFlteGxRWFYwYUc5eWFYTmhkR2x2YmxSdlQyNWliMkZ5WkNKZExDSnBjM04xWVc1alpVUmhkR1VpT2lJeU1ESXdMVEExTFRFM1ZEQTNPakEzT2pRd1dpSXNJblpoYkdsa1JuSnZiU0k2SWpJd01qQXRNRFV0TVRkVU1EYzZNRGM2TkRCYUlpd2lkbUZzYVdSVmJuUnBiQ0k2SWpJd01qQXRNRFV0TVRkVU1EYzZNRGM2TkRCYUlpd2laWGh3YVhKaGRHbHZia1JoZEdVaU9pSXlNREl3TFRBMUxURTNWREEzT2pBM09qUXdXaUlzSW1semMzVmxaQ0k2SWpJd01qQXRNRFV0TVRkVU1EYzZNRGM2TkRCYUlpd2lZM0psWkdWdWRHbGhiRk4xWW1wbFkzUWlPbnNpYVdRaU9pSmthV1E2WldKemFUcDZaRkJxTVVkUVdHcG1SVkpZZUZoUVJURlpWRmxrU2lKOUxDSmpjbVZrWlc1MGFXRnNVMk5vWlcxaElqcDdJbWxrSWpvaWFIUjBjSE02THk5aGNHa3RjR2xzYjNRdVpXSnphUzVsZFM5MGNuVnpkR1ZrTFhOamFHVnRZWE10Y21WbmFYTjBjbmt2ZGpJdmMyTm9aVzFoY3k4d2VESXpNRE01WlRZek5UWmxZVFppTnpBelkyVTJOekpsTjJObVlXTXdZalF5TnpZMVlqRTFNR1kyTTJSbU56aGxNbUprTVRoaFpUYzROVGM0TjJZMllUSWlMQ0owZVhCbElqb2lSblZzYkVwemIyNVRZMmhsYldGV1lXeHBaR0YwYjNJeU1ESXhJbjE5ZlEuam9HQjhqNHNWVjh4MDBmR2o4WnFlQU9BNjRJeHJaQk41U3B6VFlEdEx4X3R6WWhycWUtX0lURF9ydkllcXBRNEJ3a1Y2M1FsNnNJZ2R5U2lkZVM5LWciXX19.zkJwHFLAjE5RxelSGsX9KmdanVgE6bEFV-eH4rAgC8W36jKpiST8QcBIvk_Uqu3pGjiAd9tHw3Akjm5gCHqjtg
&presentation_submission=%7B%22id%22%3A%2243272b32-8f3b-4f8c-9e14-579f66457825%22%2C%22definition_id%22%3A%22didr_invite_presentation%22%2C%22descriptor_map%22%3A%5B%7B%22id%22%3A%22didr_invite_credential%22%2C%22format%22%3A%22jwt_vp%22%2C%22path%22%3A%22%24%22%2C%22path_nested%22%3A%7B%22id%22%3A%22didr_invite_credential%22%2C%22format%22%3A%22jwt_vc%22%2C%22path%22%3A%22%24.verifiableCredential%5B0%5D%22%7D%7D%5D%7D
JWT Header:
{
typ: 'JWT',
alg: 'ES256',
kid: 'did:ebsi:zdPj1GPXjfERXxXPE1YTYdJ#7j3TpaNdPNTOzOtouOOknlOLQk3JP-ykTfraWtY3GME'
}
JWT Payload:
{
iss: 'did:ebsi:zdPj1GPXjfERXxXPE1YTYdJ',
aud: 'https://api-conformance.ebsi.eu/conformance/v3/auth-mock',
sub: 'did:ebsi:zdPj1GPXjfERXxXPE1YTYdJ',
iat: 1589699260,
nbf: 1589699260,
exp: 1589699260,
nonce: 'xjfOUNf59asfn23fNk123kflsD',
jti: 'urn:uuid:0706061a-e2ca-4614-9de7-9c1451935f02',
vp: {
'@context': [ 'https://www.w3.org/2018/credentials/v1' ],
id: 'urn:uuid:0706061a-e2ca-4614-9de7-9c1451935f02',
type: [ 'VerifiablePresentation' ],
holder: 'did:ebsi:zdPj1GPXjfERXxXPE1YTYdJ',
verifiableCredential: [
'eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6ImRpZDplYnNpOnp2SFdYMzU5QTNDdmZKbkNZYUFpQWRlI0YwcjVPeXRfbGFodnZ6Nk1XbFlzM21jWU5LWmlpUWRVZnF2OHRzaEhOOXcifQ.eyJpc3MiOiJkaWQ6ZWJzaTp6dkhXWDM1OUEzQ3ZmSm5DWWFBaUFkZSIsInN1YiI6ImRpZDplYnNpOnpkUGoxR1BYamZFUlh4WFBFMVlUWWRKIiwiaWF0IjoxNTg5Njk5MjYwLCJuYmYiOjE1ODk2OTkyNjAsImV4cCI6MTU4OTY5OTI2MCwianRpIjoidXJuOnV1aWR1bmRlZmluZWQiLCJ2YyI6eyJAY29udGV4dCI6WyJodHRwczovL3d3dy53My5vcmcvMjAxOC9jcmVkZW50aWFscy92MSJdLCJpZCI6InVybjp1dWlkOnVuZGVmaW5lZCIsInR5cGUiOlsiVmVyaWZpYWJsZUNyZWRlbnRpYWwiLCJWZXJpZmlhYmxlQXR0ZXN0YXRpb24iLCJWZXJpZmlhYmxlQXV0aG9yaXNhdGlvblRvT25ib2FyZCJdLCJpc3N1YW5jZURhdGUiOiIyMDIwLTA1LTE3VDA3OjA3OjQwWiIsInZhbGlkRnJvbSI6IjIwMjAtMDUtMTdUMDc6MDc6NDBaIiwidmFsaWRVbnRpbCI6IjIwMjAtMDUtMTdUMDc6MDc6NDBaIiwiZXhwaXJhdGlvbkRhdGUiOiIyMDIwLTA1LTE3VDA3OjA3OjQwWiIsImlzc3VlZCI6IjIwMjAtMDUtMTdUMDc6MDc6NDBaIiwiY3JlZGVudGlhbFN1YmplY3QiOnsiaWQiOiJkaWQ6ZWJzaTp6ZFBqMUdQWGpmRVJYeFhQRTFZVFlkSiJ9LCJjcmVkZW50aWFsU2NoZW1hIjp7ImlkIjoiaHR0cHM6Ly9hcGktcGlsb3QuZWJzaS5ldS90cnVzdGVkLXNjaGVtYXMtcmVnaXN0cnkvdjIvc2NoZW1hcy8weDIzMDM5ZTYzNTZlYTZiNzAzY2U2NzJlN2NmYWMwYjQyNzY1YjE1MGY2M2RmNzhlMmJkMThhZTc4NTc4N2Y2YTIiLCJ0eXBlIjoiRnVsbEpzb25TY2hlbWFWYWxpZGF0b3IyMDIxIn19fQ.joGB8j4sVV8x00fGj8ZqeAOA64IxrZBN5SpzTYDtLx_tzYhrqe-_ITD_rvIeqpQ4BwkV63Ql6sIgdySideS9-g'
]
}
}
3. Filling the Trusted Registry
After obtaining the Access Token in Step 2, the next step involves interacting with the Trusted Registry using its JSON RPC API. This includes selecting and utilising the appropriate method based on specific requirements. The process generally involves building a transaction, receiving the Ethereum transaction for signing, and then submitting the signed transaction back to the Trusted Registry.
The available methods and their required parameters are detailed in the TIR JSON-RPC API documentation.