Skip to main content
European CommissionEBSI European Blockchain
Get Help

Commands reference

This section describe the complete list of commands that can be called in the command line interface.

Set, Using, View, Env, Run, Exit​

using user <algorithm> <didMethod> <privateKey> <did> <keyId>

Command to load a client in the CLI with one of the supported algorithms (ES256, RS256, EdDSA).

Params:

  • algorithm (optional): Algorithm. It must be ES256K (default), ES256, RS256, or EdDSA. Use "null" to remove the user.
  • didMethod (optional): Did method version. It must be "did1" (default, legal entities), or "did2" (natural persons).
  • privateKey (optional): Private Key in hex string or JWK format. By default it creates a random key. The hex string is only valid if the algorithm selected is ES256K.
  • did (optional): DID of the client. It should start with "did:ebsi" (or another did method registered in the did registry). There is no specific format for the complete did, but it is recommend to use in the third section a 256-bit number encoded in base58. By default it defines a random DID.
  • keyId (optional): Key identifier registered in the verifications methods of the did document.

Examples:

  • using user ES256K did1 f19863112d798add7c8df9a100a9ed961e7e7986c2e9042506840c8695e38800 did:ebsi:zkqR9GCLrLYbkubAjuqQZAz
  • using user ES256 did2
  • using user ES256 did1 {"kty":"EC","crv":"P-256","x":"...","y":"...","d":"..."} did:ebsi:zkqR9GCLrLYbkubAjuqQZAz keys-2
  • using user null (remove user)
How to re-login with the CLI

Using the example here:

The private keys would be:

  • ES256K - The string in privateKeyHex without the first two characters (which will be 0x):
3b6e9be143d5c7f30caf3b3c89bab43c220722711c1dda2e632f660dc61c0a4f
  • ES256 - The JSON object: keys > ES256 > privateKeyJwk
{
  "kty": "EC",
  "crv": "P-256",
  "x": "Vm7_Vhz07e9UoblDw1rmd29bV6ykcut4npLnqhhQlVk",
  "y": "uISs1AK-TVo0duSg3AvFuBNgBPp7ex4dWmYvkFN8uRk",
  "d": "O26b4UPVx_MMrzs8ibq0PCIHInEcHdouYy9mDcYcCk8"
}

and the keyID would be:

  • ES256K - keys > ES256K > id
"ES256K": {
      "id": "k0G8kZ0UxsxGLYiiAhRUgtLtFzu-ZpbvzFtpJIH63ZI"
}
  • ES256 - keys > ES256 > id
"ES256": {
      "id": "eJYROV5PYyRZxjF7QABzsd7ooTw5bFNm2Ytt6bAxySQ"
}

Note that keyID can be empty and the app will generate it automatically by calculating the thumbprint of the key.

So if we put this all together here are the commands you would need to re-present your keys to the CLI:

Command
==> using user {KEY_TYPE} did1 {KEY} {DID} {KEY_ID}

==> using user ES256K did1 3b6e9be143d5c7f30caf3b3c89bab43c220722711c1dda2e632f660dc61c0a4f did:ebsi:zzcJJuM4Z4AUKdL8kdMEKNw k0G8kZ0UxsxGLYiiAhRUgtLtFzu-ZpbvzFtpJIH63ZI
==> using user ES256 did1 {"kty":"EC","crv":"P-256","x":"Vm7_Vhz07e9UoblDw1rmd29bV6ykcut4npLnqhhQlVk","y":"uISs1AK-TVo0duSg3AvFuBNgBPp7ex4dWmYvkFN8uRk","d":"O26b4UPVx_MMrzs8ibq0PCIHInEcHdouYy9mDcYcCk8"} did:ebsi:zzcJJuM4Z4AUKdL8kdMEKNw eJYROV5PYyRZxjF7QABzsd7ooTw5bFNm2Ytt6bAxySQ

using ethuser <privateKey> <did>

Command to call using user ES256K <didMethod> <privateKey> <did>.

using app <name> <privateKey>

Command to load a Trusted App in the CLI. It also calls the Trusted Apps Registry to get the application id.

Params:

  • name: Application name
  • privateKey: Private key in hexadecimal format.

Examples:

  • using app my-app f19863112d798add7c8df9a100a9ed961e7e7986c2e9042506840c8695e38800

using token <token>

Command to setup a bearer token for the subsequents calls to the APIs. It's also possible to load a JWT previously saved in the CLI (see set var) by referencing its name.

Params:

  • token: JWT to set in the headers. Leave it empty to remove the token from the headers.

Examples:

  • using token eyJ0eXAiOiJ...
  • using token mySioptoken
  • using token token1
  • using token (token removed)

using oauth2token <token>

Command to load a JWT. This JWT is added in the headers when calling Ledger API if the SIOP token is not defined (see using token <token>). When a transaction is broadcasted to the blockchain the script will use this token to access Ledger API and it will wait for the transaction to be mined by checking the transaction receipt. It's also possible to load a JWT previously saved in the CLI (see set var) by referencing its name.

Params:

  • token: JWT to set in the headers when accessing Ledger API. Leave it empty to remove the token from the headers.

Examples:

  • using oauth2token eyJ0eXAiOiJ...
  • using oauth2token myOauth2Token
  • using oauth2token token1
  • using oauth2token (token removed)

set <var> <value>

Command to set a variable. Use it to load different JWTs in the CLI. You can also store the results when calling the different APIs.

Params:

  • var: Variable name
  • value: Value to store

Examples:

  • set token1 eyJhbG...
  • mytoken: authorisation siop

view <id>

Command to view the data stored in the internal variables.

Params:

  • id: ID of the variable

Examples:

  • view token (JWT used in the headers).
  • view oauth2token (JWT used in the headers of Ledger API).
  • view user (view user set with using user).
  • view app (view app set with using app).
  • view transactionInfo (view relevant info related to the most recent transaction built/sent).

env <environment>

Command to set the environment. By default the CLI starts pointing to Test Environment.

Examples:

  • env test
  • env pilot
  • env conformance

run <file>

This repository contains a script folder with some scripts that provide you examples of how you can easily run multiple commands in a single execution. You can also create your own scripts in any folder and reference the path when running the command.

Examples:

  • run onboarding
  • run local/my-script.txt

exit

Command to exit from the CLI.

Compute​

compute signTransaction <unsignedTransaction>

Command to sign a transaction with the private key defined in using user. It's also possible to load it from the saved variables by referencing its name.

Params:

  • unsignedTransaction: JSON with the unsigned transaction (ethereum).

Examples:

  • compute signTransaction 0xf9...
  • compute signTransaction utx
  • sgnTx: compute signTransaction utx

compute createPresentationJwt <verifiableCredential>

Command to generate a Verifiable Presentation using the "vp_jwt" format. The presentation is signed with the user defined in using user.

Params:

  • verifiableCredential: Verifiable credential. It's also possible to load it from the saved variables by referencing its name.

Examples:

  • compute createPresentationJwt eyJhb...
  • compute createPresentationJwt {"@context":"..."}
  • compute createPresentationJwt vc

compute createVcJwt <vcPayload> <jwtPayload> <alg>

Command to create a verifiable credential with JWT format. It automatically defines relevant data like context, type, isssuance date, and expiration data. The credential is signed with the user defined in using user.

Params:

  • vcPayload: Payload to include in "vc" field. Context, id, type, issuer, issuance/expiration date are automatically generated but then can be overwritten.
  • jwtPayload: Payload to include outside "vc" field.
  • alg (optional): Signing algorithm to be used. It should be ES256K (default), ES256, RS256, or EdDSA. And the private key should be defined for that algorithm (see using user).

Examples:

  • compute createVcJwt {"credentialSubject":{"id":"did:ebsi:123"}} {"sub":"did:ebsi:123"}
  • vc: compute createVcJwt {"credentialSubject":{"id":"did:ebsi:123"}} {"sub":"did:ebsi:123"} ES256

compute signJwt <payload> <alg> <headers>

Command to create a generic JWT.

Params:

  • payload: JSON payload.
  • alg: signing algorithm.
  • headers: JSON headers

compute wait <seconds>

Command to wait seconds before calling a new command. It is useful for scripts when it's necessary to wait some time, like mining a transaction in the blockchain.

Params:

  • seconds: number of seconds to wait.

compute userPin <did>

Command to compute the user's PIN code used in the Issue to Holder test.

Params:

  • did: DID of the natural person

compute schemaId <schema> <base>

Command to compute the schema ID based on the content.

Params:

  • schema: JSON schema
  • base: Output format. It should be "base16" or "base58btc" (default).

compute checkStatusList2021CredentialSchema <credential>

Command to check if a credential is conformant with the Status List 2021 credential schema. It is useful to debug errors when registering a proxy in the Trusted Issuers Registry because this is one of the validations done in the API.

Params:

  • credential: Payload of the credential in JSON format.

compute verifyVcJwt <vcJwt> <options> <expectedResult>

Command to verify if a VC is valid or not.

Params:

  • vcJwt: Verifiable credential in JSON format.
  • options: Verifiable credential options.
  • expectedResult: Set expectRevoked if you expect this VC to be revoked. Otherwise leave it empty.

Examples:

  • compute verifyVcJwt ey... {"skipCredentialSubjectValidation":true}
  • compute verifyVcJwt ey... {} expectRevoked

compute verifyAuthenticationRequest <request>

Command to verify an authentication request by checking the signature and did in the request. It return the client_id specified in the request. It's also possible to load it from the saved variables by referencing its name. This command is used during the SIOP authentication with the authorisation API.

Params:

  • request: JSON containing at least the fields client_id and request (JWT).

Examples:

  • compute verifyAuthenticationRequest {"client_id":"https//...","request":"eyJ0e..."}
  • compute verifyAuthenticationRequest request

compute verifySessionResponse <response>

Command to verify a session response by checking the nonce and signature in the Ake response. It decrypts and returns the access token contained in the Ake response. For decryption it uses the private key defined in the command using user. It's also possible to load the response from the saved variables by referencing its name. This command is used during the SIOP authentication with the authorisation API.

Params:

  • response: JSON containing the fields nonce (reference to check in the response), and response (using Ake protocol format).

Examples:

  • compute verifySessionResponse {"nonce":"3a4...","response":{"ake1_enc_payload":"9ed9b3b..."}
  • compute verifySessionResponse response

compute did2 <jwk>

Command to compute the DID for natural person (did:key) given a jwk.

Params:

  • jwk: JWK of the natural person.

compute sha256 <data>

Command to compute the sha256 of some data.

Params:

  • data: String or JSON object to hash.

compute decodeJWT <jwt>

Command to decode a jwt. It's also possible to load it from the saved variables by referencing its name.

Params:

  • jwt: JWT to decode.

Examples:

  • compute decodeJWT eyJ0e...
  • compute decodeJWT myJwt

compute decodeBase64 <data>

Command to decode data encoded in base64. It's also possible to load it from the saved variables by referencing its name.

Params:

  • data: Data to decode.

Examples:

  • compute decodeBase64 eyJ0e...
  • compute decodeBase64 myData

compute decodeBase64url <data>

Command to decode data encoded in base64url. It's also possible to load it from the saved variables by referencing its name.

Params:

  • data: Data to decode.

Examples:

  • compute decodeBase64url eyJ0e...
  • compute decodeBase64url myData

compute decodeHex <data>

Command to decode data encoded as hex string. It's also possible to load it from the saved variables by referencing its name.

Params:

  • data: Data to decode.

Examples:

  • compute decodeHex 0x41df...
  • compute decodeHex 41df...

compute timestampId <hash>

Command to get the multibase64url of the sha256 of a specific hash, which corresponds with the protocol used in Timestamp API to reference the IDs.

Params:

  • hash: sha256 of the timestamped data.

Examples:

  • compute timestampId 0x37926887dc319ac87cda01caf411bccb9ab8933d97cf3c2d57d3e13aa8bad580

compute recordId <address> <blockNumber> <hash>

Command to compute the record ID stored in Timestamp API. This record is computed from the address that timestamped the data, the block number, and hash of the data.

Important note: This record ID is computed from the first version submitted to the blockchain.

Params:

  • address: Ethereum address.
  • blockNumber: Block number of the timestamp
  • hash: sha256 of the timestamped data.

Examples:

  • compute timestampId 0x37926887dc319ac87cda01caf411bccb9ab8933d97cf3c2d57d3e13aa8bad580

compute randomID

Command to compute a random ID of 32 bytes

compute thumbprint <hexOrJwk>

Command to compute the thumbprint of a key.

Params:

  • hexOrJwk: Key in hex format or JWK. The hex format is only for keys with alg ES256K.

Conformance​

Set of instructions to interact with the conformance service. Check also the scripts located in scripts/wctv3 with complete flows.

conformance get <url>

Command to GET in conformance service. It is useful to get the conformance logs.

Params:

  • url: Path to get.

Examples:

  • data: conformance get /logs/5fd122e1-c5e5-40a6-b448-00e0f21f9d7e
  • conformance get /logs/ conformanceId
  • conformance get /health

conformance clientMockInitiate

Some of the tests for the Wallet Conformance Testing require the creation of a server to be used in the PEXv2/OpenID for VP protocol. This command helps you to create this server in the conformance service side, it is called the Client Mock. Take into account that this is a temporary API just for testing purposes and it's persistency it's not guaranteed.

Examples:

  • conformance clientMockInitiate

once it's created run view user to see the URL of your client.

conformance clientMockUpdateList <statusIndex> <statusListIndex> <value>

Command to setup, in the client mock, a service to get the status of revocation of a list of VCs by following the StatusList2021 standard. This command can also be used to update the status of these VCs. Take into account that this service is only for testing purposes and should not be used in production.

Params:

  • statusIndex: Status index of the url. For instance, use "1" when targeting /credentials/status/1.
  • statusListIndex: Bit position of the status of the credential.
  • value: 0 for valid, 1 for revoked.

Examples:

  • conformance clientMockUpdateList 1 0 0

conformance authMockAuthorize <openIdCredentialIssuer> <openIdConfiguration> <requestedTypes> <alg> <codeVerifier> <issuerState>

Command to call the /authorize endpoint of the auth mock in conformance service. The redirect is intercepted and this command returns the query params in the location field of the headers.

Params:

  • openIdCredentialIssuer: OpenID credential issuer. It is obtained with conformance get /issuer-mock/.well-known/openid-credential-issuer.
  • openIdConfiguration: OpenID configuration. It is obtained with conformance get /auth-mock/.well-known/openid-configuration.
  • requestedTypes: Array of requested types.
  • alg (optional): Signing algorithm (ES256 by default).
  • codeVerifier (optional): Code verifier in case of using PKCE challenge.
  • issuerState (optional): Issuer state to be included in the query params.

Examples:

  • conformance authMockAuthorize {"authorization_server":"https://api-conformance.ebsi.eu/conformance/v3/auth-mock","credential_issuer":"https://api-conformance.ebsi.eu/conformance/v3/issuer-mock"} {"authorization_endpoint":"https://api-conformance.ebsi.eu/conformance/v3/auth-mock/authorize"} ["VerifiableCredential","VerifiableAttestation","VerifiableAuthorisationToOnboard"] ES256

conformance authMockDirectPostIdToken <openIdCredentialIssuer> <openIdConfiguration> <issuerRequest> <alg>

Command to call the direct post endpoint of the auth mock of the conformance service by presenting an ID Token. The redirect is intercepted and this command returns the query params in the location field of the headers.

Params:

  • openIdCredentialIssuer: OpenID credential issuer. It is obtained with conformance get /issuer-mock/.well-known/openid-credential-issuer.
  • openIdConfiguration: OpenID configuration. It is obtained with conformance get /auth-mock/.well-known/openid-configuration.
  • issuerRequest: Object containing state and nonce, which are obtained from the /authorize endpoint.
  • alg (optional): Signing algorithm (ES256 by default).

Examples:

  • conformance authMockDirectPostIdToken {"authorization_server":"https://api-conformance.ebsi.eu/conformance/v3/auth-mock","credential_issuer":"https://api-conformance.ebsi.eu/conformance/v3/issuer-mock"} {"redirect_uris":["https://api-conformance.ebsi.eu/conformance/v3/auth-mock/direct_post"]} {"state":"6dfa6336-4dfd-4461-927f-0e8c5e482cee","client_id":"https://api-conformance.ebsi.eu/conformance/v3/auth-mock","redirect_uri":"https://api-conformance.ebsi.eu/conformance/v3/auth-mock/direct_post","response_type":"id_token","response_mode":"direct_post","scope":"openid","nonce":"8b0fbc51-f020-4811-9d8f-0bc8faaaf44a","request_uri":"https://api-conformance.ebsi.eu/conformance/v3/auth-mock/request_uri/56774e12-0d71-4089-9446-7b316ec93955"} ES256

conformance authMockDirectPostVpToken <openIdConfiguration> <issuerRequest> <vpJwt> <type>

Command to call the direct post endpoint of the auth mock of the conformance service by presenting a VP Token. The redirect is intercepted and this command returns the query params in the location field of the headers.

Params:

  • openIdConfiguration: OpenID configuration. It is obtained with conformance get /auth-mock/.well-known/openid-configuration.
  • issuerRequest: Object containing state and nonce, which are obtained from the /authorize endpoint.
  • vpJwt: Verifiable Presentation in JWT format.
  • type: It must be "holder" when making a presentation submission related to the Holder Wallet test. Or empty value for other cases.

conformance authMockToken <openIdCredentialIssuer> <openIdConfiguration> <code> <alg> <codeVerifier> <type>

Command to call the /token endpoint of the auth mock in conformance service.

Params:

  • openIdCredentialIssuer: OpenID credential issuer. It is obtained with conformance get /issuer-mock/.well-known/openid-credential-issuer.
  • openIdConfiguration: OpenID configuration. It is obtained with conformance get /auth-mock/.well-known/openid-configuration.
  • code: Code obtained from the direct post call.
  • alg (optional): Signing algorithm (ES256 by default).
  • codeVerifier (optional): Code verifier in case of using PKCE challenge.
  • type (optional): It must be authorised (default) or preAuthorised.

Examples:

  • conformance authMockToken {"authorization_server":"https://api-conformance.ebsi.eu/conformance/v3/auth-mock","credential_issuer":"https://api-conformance.ebsi.eu/conformance/v3/issuer-mock"} {"token_endpoint":"https://api-conformance.ebsi.eu/conformance/v3/auth-mock/token"} b170601e-fe20-4cf7-860f-782e0c3262fb ES256

conformance issuerMockCredential <openIdCredentialIssuer> <nonce> <requestedTypes> <alg>

Command to call the /credential endpoint of the issuer mock of conformance service. It is used to issue the credential.

Params:

  • openIdCredentialIssuer: OpenID credential issuer. It is obtained with conformance get /issuer-mock/.well-known/openid-credential-issuer.
  • nonce: c_nonce obtained from the token endpoint.
  • requestedTypes: Array of requested types.
  • alg (optional): Signing algorithm (ES256 by default).

Examples:

  • conformance issuerMockCredential {"credential_issuer":"https://api-conformance.ebsi.eu/conformance/v3/issuer-mock"} 84317381-94b1-43f2-a79d-ee134b02c3cc ["VerifiableCredential","VerifiableAttestation","VerifiableAuthorisationToOnboard"] ES256

conformance issuerMockDeferred <openIdCredentialIssuer> <acceptanceToken>

Command to call the deferred credential endpoint when receiving the credential in deferred way, like in the exchange of requesting a credential to be a Root TAO.

Params:

  • openIdCredentialIssuer: OpenID credential issuer. It is obtained with conformance get /issuer-mock/.well-known/openid-credential-issuer.
  • acceptanceToken: Acceptance token obtained from the /credential endpoint.

conformance issuerMockInitiateCredentialOffer <initiateCredentialOfferEndpoint> <credentialType>

Command to initiate the credential offer in the issuer mock of the conformance service. It is used during the Holder Wallet test.

Params:

  • initiateCredentialOfferEndpoint: Initiate credential offer endpoint.
  • credentialType: Requested type.

Examples:

  • conformance issuerMockInitiateCredentialOffer https://api-conformance.ebsi.eu/conformance/v3/issuer-mock/initiate-credential-offer CTWalletCrossAuthorisedInTime

conformance getCredential <type> <alg> <vc> <issuer>

Command to make the complete presentation exchange (auth mock and issuer mock) in order to get a Verifiable Credential.

Params:

  • type: Type of presentation exchange to be stablished with the issuer. It must be "onboard", "ti", "tao", "roottao", "ctrevocable", or "qualification".
  • alg (optional): Signing algorithm (ES256 by default).
  • vc (optional): VC to be wrapped in the verifiable presentation.
  • issuer (optional): DID of the issuer if the target is the client mock of conformance service. Otherwise the issuer mock will be targeted.

Examples:

  • conformance getCredential onboard

conformance holder <credentialType> <communicationType> <inputAlg> <vc> <typeCredentialOffer> <inputIssuer>

Command to make the complete presentation exchange in order to get a credential for a natural person.

Params:

  • credentialType: Credential type to be requested. It must be one of the following values: CTWalletSameAuthorisedInTime, CTWalletCrossAuthorisedInTime, CTWalletSameAuthorisedDeferred, CTWalletCrossAuthorisedDeferred, CTWalletQualificationCredential, CTWalletSamePreAuthorisedInTime, CTWalletCrossPreAuthorisedInTime, CTWalletSamePreAuthorisedDeferred, CTWalletCrossPreAuthorisedDeferred, or VerifiablePortableDocumentA1.
  • communicationType (optional): It must be authorisedInTime, authorisedDeferred, preAuthorisedInTime, or preAuthorisedDeferred.
  • alg (optional): Signing algorithm (ES256 by default).
  • vc (optional): VCs to be wrapped in the verifiable presentation. Use empty for no VCs.
  • typeCredentialOffer (optional): It must be credential-offer or skip-credential-offer.
  • inputIssuer (optional): DID of the issuer if the target is the client mock of conformance service. Otherwise the issuer mock will be targeted.

Examples:

  • cPda1: conformance holder VerifiablePortableDocumentA1 authorisedDeferred
  • conformance holder CTIssueQualificationCredential authorisedInTime ES256 empty skip-credential-offer
  • conformance holder CTWalletQualificationCredential authorisedInTime ES256 ["ey...", "ey..."]

conformance check <testId>

Command to call the check endpoint of the conformance service in order to verify if a test passed.

Params:

  • testId: Test ID to be checked.

Examples:

  • conformance check ct_wallet_same_pre_authorised_in_time
  • conformance check request_ct_issue_to_holder_qualification_credential
  • conformance check verifier_id_token_exchange
  • conformance check verifier_vp_revoked_vc

Authorisation API​

OpenAPI documentation

authorisation get <url>

Command to GET in Authorisation API. It is useful to check the health of the api.

Params:

  • url: Path to get.

Examples:

  • authorisation get /health

authorisation token <definitionId> <vpJwt>

Command to call the /token endpoint of Authorisation API.

Params:

  • definitionId: Definition ID. It must be "didr_invite_presentation", "didr_write_presentation", "tir_invite_presentation", "tir_write_presentation", or "timestamp_write_presentation".
  • vpJwt: Verifiable Presentation in JWT format.

authorisation auth <definitionId> <alg> <vc>

Command to make the complete authentication process in the Authorisation API in order to get an access token.

Params:

  • definitionId: Definition ID. It must be "didr_invite_presentation", "didr_write_presentation", "tir_invite_presentation", "tir_write_presentation", or "timestamp_write_presentation".
  • vc (optional): Verifiable Credential to be wrapped during the presentation.

Examples:

  • authorisation auth didr_write_presentation
  • authorisation auth didr_invite_presentation ey...

authorisation siopRequest

Command to start a SIOP authentication with authorisation api. The authorisation api will return a request.

Examples:

  • authorisation siopRequest
  • response: authorisation siopRequest

authorisation siopSession <url> <alg> <vpBase64url>

Command to call /siop-sessions in authorisation api. It uses the client defined in using user to sign the response. It returns the response received from the api. It's also possible to load the parameters from the saved variables by referencing the names.

Params:

  • url: callback url to build the response.
  • alg (optional): Signing algorithm to be used. It should be ES256K (default), ES256, RS256, or EdDSA. And the private key should be defined for that algorithm (see using user).
  • vpBase64url (optional): Data to include in the verified claims. It should be canonicalized and encoded in base64url (see compute canonicalizeBase64url)

Examples:

  • authorisation siopSession https://... ES256K eyJ0e...
  • authorisation siopSession callbackUrl ES256K myVpBase64url

authorisation siop <alg> <vcJwtEOS>

Command to establish a SIOP session with authorisation api. It uses the client defined in using user. It returns an access token. The command will perform the following steps:

  • call compute createPresentationJwt to create a verifiable presentation (only if a verifiable authorisation is provided).
  • call authorisation siopRequest to get a request from the API.
  • call compute verifyAuthenticationRequest to verify the request.
  • call authorisation siopSession to send a response to the api.
  • call compute verifySessionResponse to verify the response and get the access token.

Params:

  • alg (optional): Signing algorithm to be used. It should be ES256K (default), ES256, RS256, or EdDSA. And the private key should be defined for that algorithm (see using user).

  • vcJwtEOS (optional): Verifiable Authorisation issued by an EBSI Onboarding Service (EOS) to be wrapped in a verifiable presentation. This credential is required for natural persons.

Examples:

  • authorisation siop
  • mySiopToken: authorisation siop
  • mySiopToken: authorisation siop EdDSA
  • mySiopToken: authorisation siop ES256K ey...

authorisation oauth2 <audience>

Command to establish an Oauth2 session with authorisation api. It uses the ap defined in using app. It returns an access token. Normally this call is used together with the option to store the results.

Params:

  • audience: App audience of oauth2 token.

Examples:

  • authorisation oauth2 ledger-api
  • myOauth2Token: authorisation oauth2 ledger-api

Ledger API​

ledger <contract> <method> <params>

Command to interact with the smart contracts throught the Ledger API without calling other APIs. The contract, methods, and params are the same defined in the previous sections for DID API, Timestamp API, Trusted Apps Registry API, Trusted Issuers Registry API, and Trusted Schemas Registry API.

Examples:

  • ledger timestamp timestampHashes
  • ledger timestamp build-timestampHashes
  • ledger tir insertIssuer did:ebsi:zkqR9GCLrLYbkubAjuqQZAz {"institution":"eu"}

ledger getBlock <number>

Command to get a block by number. The JWT defined in using oauth2token is set in the headers.

Params:

  • number: Block number

Examples:

  • ledger get 123

ledger getTransactionCount <address>

Command to get the number of transactions of a particular address. The JWT defined in using oauth2token is set in the headers.

Params:

  • address: Ethereum address

Examples:

  • ledger getTransactionCount 0x2fCbc96c55e57bed5ae8BC533EF77b977Dc482d7

ledger getChainId

Command to get the chain id of the network. The JWT defined in using oauth2token is set in the headers.

Examples:

  • ledger getChainId

ledger getTransaction <id>

Command to get a transaction by its ID. The JWT defined in using oauth2token is set in the headers.

Params:

  • id: Transaction ID

Examples:

  • ledger getTransaction 0x2fCb...82d7

ledger getTransactionReceipt <id>

Command to get the receipt of a particular transaction. It also displays the revert reason for failed transactions. The JWT defined in using oauth2token is set in the headers.

Params:

  • id: Transaction ID

Examples:

  • ledger getTransactionReceipt 0x2fCb...482d7

ledger sendTransaction <signedTransaction>

Command to send transactions to the blockchain. The JWT defined in using oauth2token is set in the headers.

Params:

  • signedTransaction: signed transaction in raw format.

Examples:

  • ledger sendTransaction 0x2fCb...482d7 0x123456

proxyledger <...>

The command proxyledger has the same commands as ledger with the difference that it will call the blockchain directly without going through Ledger API. To enable this feature set the corresponding provider in TEST_BESU_PROVIDER or PILOT_BESU_PROVIDER in the env variables. This command should not be used by externals.

Examples:

  • proxyledger timestamp timestampHashes
  • proxyledger timestamp build-timestampHashes
  • proxyledger tir insertIssuer did:ebsi:zkqR9GCLrLYbkubAjuqQZAz {"institution":"eu"}
  • proxyledger getTransactionReceipt 0x2fCb...482d7

DID Registry API​

OpenAPI documentation

did get <url>

Command to GET in the DID Registry API. All endpoints are open to the public.

Params:

  • url: Path to get.

Examples:

  • did get /identifiers
  • did get /identifiers?controller=did:ebsi:zkqR9GCLrLYbkubAjuqQZAz
  • did get /identifiers/did:ebsi:zkqR9GCLrLYbkubAjuqQZAz

did (build-)insertDidDocument <did> <baseDocument> <publicKey> <notBefore> <notAfter> <vMethodId>

Command to insert a new DID document. The JWT is set in the headers.

Use the build- prefix to call the API helper to build the transaction. If this prefix is not set then the command will perform the following steps:

  • call did build-insertDidDocument to build an unsigned transaction.
  • call compute signTransaction to sign the transaction with the user defined in using user.
  • call did sendSignedTransaction to send the transaction signed.
  • call view transactionInfo to see relevant data for this transaction.

Params:

  • did (optional): DID to insert. By default it uses the did defined in the command using user.
  • baseDocument (optional): JSON document containing the context.
  • publicKey (optional): Public key for the ES256K key.
  • notBefore (optional): Time where the key is valid.
  • notAfter (optional): Time where the key expires (5 years by default).
  • vMethodId (optional): Verification Method ID. By default it is the thumbprint of the public key.

Examples:

  • did insertDidDocument
  • did insertDidDocument did:ebsi:zkqR9GCLrLYbkubAjuqQZAz

did (build-)updateBaseDocument <did> <baseDocument>

Command to update the base document of a DID document. Use the build- prefix to just call the API helper without signing the transaction.

Params:

  • did: DID to update.
  • baseDocument: JSON document containing the context.

did (build-)addController <did> <controller>

Command to add a controller to a DID document. Use build- prefix to just call the API helper without signing the transaction.

Params:

  • did: DID to update.
  • controller: DID of the new controller.

did (build-)removeController <did> <controller>

Command to remove a controller from a DID document. Use build- prefix to just call the API helper without signing the transaction.

Params:

  • did: DID to update.
  • controller: DID of the controller to removed.

did (build-)addVerificationMethod <did> <publicKeyOrAlg> <vMethodId>

Command to add a verification method to a DID document. Use build- prefix to just call the API helper without signing the transaction.

Params:

  • did: DID to update.
  • publicKeyOrAlg: Public key in hex format for ES256K or JWT format for other algs. You can also specify the algorithm and the app will take the corresponding key from the data of the loaded user.
  • vMethodId (optional): Verification method ID. If it is not defined it is taken from the keys of the loaded user.

Examples:

  • did addVerificationMethod user.did ES256

did (build-)addVerificationRelationship <did> <name> <vMethodIdOrAlg> <notBefore> <notAfter>

Command to add a verification relationship to a DID document. Use build- prefix to just call the API helper without signing the transaction.

Params:

  • did: DID to update.
  • name: Name of the relationship ("authentication", "assertionMethod", "keyAgreement","capabilityInvocation", or "capabilityDelegation").
  • vMethodIdOrAlg: Verification Method ID. You can also specify the algorithm and the app will take the corresponding ID from the loaded user.
  • notBefore (optional): Time where the relationship becomes valid. By default it uses the actual time.
  • notAfter (optional): Time where the relationship becomes invalid. By default it uses 5 years in the future.

Examples:

  • did addVerificationRelationship user.did assertionMethod ES256

did (build-)revokeVerificationMethod <did> <vMethodIdOrAlg> <notAfter>

Command to revoke a verification method and remove the corresponding relationships. Use build- prefix to just call the API helper without signing the transaction.

Params:

  • did: DID to update.
  • vMethodIdOrAlg: Verification Method ID. You can also specify the algorithm and the app will take the corresponding ID from the loaded user.
  • notAfter: Time in the past where the verification method id should be revoked. By default it uses the actual time.

did (build-)expireVerificationMethod <did> <vMethodIdOrAlg> <notAfter>

Command to expire a verification method and remove the corresponding relationships. Use build- prefix to just call the API helper without signing the transaction.

Params:

  • did: DID to update.
  • vMethodIdOrAlg: Verification Method ID. You can also specify the algorithm and the app will take the corresponding ID from the loaded user.
  • notAfter: Time in the future where the verification method id should be expired.

did (build-)rollVerificationMethod <did> <publicKeyOrAlg> <notBefore> <notAfter> <oldVMethodId> <duration> <vMethodId>

Command to roll a verification method, that is, revoke a key and change it for another one. Use build- prefix to just call the API helper without signing the transaction.

Params:

  • did: DID to update.
  • publicKeyOrAlg: Public key in hex format for ES256K or JWT format for other algs. You can also specify the algorithm and the app will take the corresponding key from the data of the loaded user.
  • notBefore: Time where the new key becomes valid.
  • notAfter: Time where the new key becomes invalid.
  • oldVMethodId: ID of the verification method that will be revoked.
  • duration: Transition time where both keys are valid.
  • vMethodId: New verification method ID.

did sendSignedTransaction <unsignedTransaction> <signedTransaction>

Command to send a signed transaction to the DID Registry. The JWT is set in the headers. It's also possible to load the parameters from the saved variables by referencing the names.

Params:

  • unsignedTransaction: JSON with the unsigned transaction.
  • signedTransaction: Signed transaction in raw format.

Examples:

  • did sendSignedTransaction {"from":"0x6b...} 0xf9022...
  • did sendSignedTransaction utx sgntx

Timestamp API​

OpenAPI documentation

timestamp get <url>

Command to GET in the Timestamp API. All endpoints are open to the public.

Params:

  • url: Path to get.

Examples:

  • timestamp get /timestamps
  • timestamp get /timestamps/uMHh...
  • timestamp get /hash-algorithms
  • timestamp get /records

timestamp (build-)insertHashAlgorithm <outputLength> <ianaName> <oid> <status> <multihash>

Command to insert a new hash algorithm. The JWT is set in the headers. This method requires admin rights in the Trusted Apps Registry.

Use the build- prefix to call the API helper to build the transaction. If this prefix is not set then the command will perform the following steps:

  • call timestamp build-insertHashAlgorithm to build an unsigned transaction.
  • call compute signTransaction to sign the transaction with the user defined in using user.
  • call timestamp sendSignedTransaction to send the transaction signed.
  • call view transactionInfo to see relevant data for this transaction.

Params:

  • outputLength (optional): JSON data to store. By default it is 1.
  • ianaName (optional): IANA name. By default it is "undefined".
  • oid (optional): OID. By default it is "undefined".
  • status (optional): Status. It must be 1 (default) or 2 which corresponds with active or revoked respectively.
  • multihash (optional): Multihash identifier. By default it uses de ianaName.

Examples:

  • timestamp insertHashAlgorithm 256 sha-256 2.16.840.1.101.3.4.2.1 1 sha2-256
  • timestamp insertHashAlgorithm 512 sha3-512 2.16.840.1.101.3.4.2.10 1 sha3-512

timestamp (build-)updateHashAlgorithm <hashAlgId> <outputLength> <ianaName> <oid> <status> <multihash>

Command to update an existing hash algorithm. The JWT is set in the headers. This method requires admin rights in the Trusted Apps Registry.

Use the build- prefix to call the API helper to build the transaction. If this prefix is not set then the command will perform the following steps:

  • call timestamp build-updateHashAlgorithm to build an unsigned transaction.
  • call compute signTransaction to sign the transaction with the user defined in using user.
  • call timestamp sendSignedTransaction to send the transaction signed.
  • call view transactionInfo to see relevant data for this transaction.

Params:

  • hashAlgId: Hash Algorithm ID to update.
  • outputLength (optional): JSON data to store. By default it is 1.
  • ianaName (optional): IANA name. By default it is "undefined".
  • oid (optional): OID. By default it is "undefined".
  • status (optional): Status. It must be 1 (default) or 2 which corresponds with active or revoked respectively.
  • multihash (optional): Multihash identifier. By default it uses de ianaName.

Examples:

  • timestamp updateHashAlgorithm 1 256 sha-256 2.16.840.1.101.3.4.2.1 1 sha2-256
  • timestamp updateHashAlgorithm 7 512 sha3-512 2.16.840.1.101.3.4.2.10 1 sha3-512

timestamp (build-)timestampRecordHashes <data> <info>

Command to timestamp data and create a record of it with some info. The JWT is set in the headers.

Use the build- prefix to call the API helper to build the transaction. If this prefix is not set then the command will perform the following steps:

  • call timestamp build-timestampRecordHashes to build an unsigned transaction.
  • call compute signTransaction to sign the transaction with the user defined in using user.
  • call timestamp sendSignedTransaction to send the transaction signed.
  • call view transactionInfo to see relevant data for this transaction.

Params:

  • data (optional): JSON data to timestamp. By default it creates random data.
  • info (optional): JSON info to insert in the record. By default it creates random data.

Examples:

  • timestamp timestampRecordHashes
  • timestamp timestampRecordHashes {"data":"my data"} {"info":"test"}

timestamp (build-)timestampVersionHashes <previousHash> <data> <info>

Command to create a new version of an existing record given the previous version hash. This new version is timestamped. Use it when you don't have the recordId but you have the hash that was timestamped in the previous version. You can not use this function if several records share the same hash, for such cases use timestampRecordVersionHashes. The JWT is set in the headers. Only record owners are allowed to perform this operation.

Use the build- prefix to call the API helper to build the transaction. If this prefix is not set then the command will perform the following steps:

  • call timestamp build-timestampVersionHashes to build an unsigned transaction.
  • call compute signTransaction to sign the transaction with the user defined in using user.
  • call timestamp sendSignedTransaction to send the transaction signed.
  • call view transactionInfo to see relevant data for this transaction.

Params:

  • previousHash: Hash timestamped in a previous version
  • data (optional): JSON data to timestamp. By default it creates random data.
  • info (optional): JSON info to insert in the new version of the record. By default it creates random data.

Examples:

  • timestamp timestampVersionHashes 0x12f5...
  • timestamp timestampVersionHashes 0x12f5... {"data":"my data"} {"info":"test"}

timestamp (build-)timestampRecordVersionHashes <recordId> <data> <info>

Command to create a new version of an existing record. This new version is timestamped. The JWT is set in the headers. Only record owners are allowed to perform this operation.

Use the build- prefix to call the API helper to build the transaction. If this prefix is not set then the command will perform the following steps:

  • call timestamp build-timestampRecordVersionHashes to build an unsigned transaction.
  • call compute signTransaction to sign the transaction with the user defined in using user.
  • call timestamp sendSignedTransaction to send the transaction signed.
  • call view transactionInfo to see relevant data for this transaction.

Params:

  • recordId: Record ID in hex string format
  • data (optional): JSON data to timestamp. By default it creates random data.
  • info (optional): JSON info to insert in the new version of the record. By default it creates random data.

Examples:

  • timestamp timestampRecordVersionHashes 0x12f5...
  • timestamp timestampRecordVersionHashes 0x12f5... {"data":"my data"} {"info":"test"}

timestamp (build-)insertRecordOwner <recordId> <ownerId> <notBefore> <notAfter>

Command to insert a new owner in an existing record. The JWT is set in the headers. Only record owners are allowed to perform this operation.

Use the build- prefix to call the API helper to build the transaction. If this prefix is not set then the command will perform the following steps:

  • call timestamp build-insertRecordOwner to build an unsigned transaction.
  • call compute signTransaction to sign the transaction with the user defined in using user.
  • call timestamp sendSignedTransaction to send the transaction signed.
  • call view transactionInfo to see relevant data for this transaction.

Params:

  • recordId: Record ID in hex string format
  • ownerId: Ethereum address of new owner.
  • notBefore (optional): Point in time when the owner becomes valid. It should be defined in epoch time. By default it takes the actual time.
  • notAfter (optional): Point in time when the owner becomes invalid. It should be defined in epoch time. By default it is 0 (indefinite).

Examples:

  • timestamp insertRecordOwner 0x12f5... 0xab54...
  • timestamp insertRecordOwner 0x12f5... 0xab54... 1625568669 1657104669

timestamp (build-)revokeRecordOwner <recordId> <ownerId>

Command to revoke new owner from an existing record and put it in the revoked list. The JWT is set in the headers. Only record owners are allowed to perform this operation.

Use the build- prefix to call the API helper to build the transaction. If this prefix is not set then the command will perform the following steps:

  • call timestamp build-revokeRecordOwner to build an unsigned transaction.
  • call compute signTransaction to sign the transaction with the user defined in using user.
  • call timestamp sendSignedTransaction to send the transaction signed.
  • call view transactionInfo to see relevant data for this transaction.

Params:

  • recordId: Record ID in hex string format.
  • ownerId: Ethereum address of the owner to revoke.

Examples:

  • timestamp revokeRecordOwner 0x12f5... 0xab54...

timestamp (build-)insertRecordVersionInfo <recordId> <versionId> <info>

Command to insert new info to a version of an existing record. The JWT is set in the headers. Only record owners are allowed to perform this operation.

Use the build- prefix to call the API helper to build the transaction. If this prefix is not set then the command will perform the following steps:

  • call timestamp build-insertRecordVersionInfo to build an unsigned transaction.
  • call compute signTransaction to sign the transaction with the user defined in using user.
  • call timestamp sendSignedTransaction to send the transaction signed.
  • call view transactionInfo to see relevant data for this transaction.

Params:

  • recordId: Record ID in hex string format.
  • versionId: Number of the version.
  • info (optional): JSON info to insert in the version.

Examples:

  • timestamp insertRecordVersionInfo 0x12f5... 1
  • timestamp insertRecordVersionInfo 0x12f5... 1 {"info":"test"}

timestamp (build-)detachRecordVersionHash <recordId> <versionId> <hash>

Command to remove a hash from a version of an existing record. The JWT is set in the headers. Only record owners are allowed to perform this operation.

Use the build- prefix to call the API helper to build the transaction. If this prefix is not set then the command will perform the following steps:

  • call timestamp build-detachRecordVersionHash to build an unsigned transaction.
  • call compute signTransaction to sign the transaction with the user defined in using user.
  • call timestamp sendSignedTransaction to send the transaction signed.
  • call view transactionInfo to see relevant data for this transaction.

Params:

  • recordId: Record ID in hex string format.
  • versionId: Number of the version.
  • hash: Hash of timestamp to detach.

Examples:

  • timestamp detachRecordVersionHash 0x12f5... 1 0xfd45...

timestamp (build-)appendRecordVersionHashes <recordId> <versionId> <data> <info>

Command to include more hashes to an existing version. For instance, use it if you want to have different hashes (sha2-256, sha3-512, etc) of the same data. The JWT is set in the headers. Only record owners are allowed to perform this operation.

DISCLAIMER: In the current version the CLI the "data" is hashed with sha2-256. Future versions will include more algorithms.

Use the build- prefix to call the API helper to build the transaction. If this prefix is not set then the command will perform the following steps:

  • call timestamp build-appendRecordVersionHashes to build an unsigned transaction.
  • call compute signTransaction to sign the transaction with the user defined in using user.
  • call timestamp sendSignedTransaction to send the transaction signed.
  • call view transactionInfo to see relevant data for this transaction.

Params:

  • recordId: Record ID in hex string format
  • versionId: Number of the version.
  • data (optional): JSON data to timestamp. By default it creates random data.
  • info (optional): JSON info to append in the version of the record. By default it creates random data.

Examples:

  • timestamp appendRecordVersionHashes 0x12f5... 1
  • timestamp appendRecordVersionHashes 0x12f5... 1 {"data":"my data"} {"info":"test"}

timestamp (build-)timestampHashes <data>

Command to timestamp data. The JWT is set in the headers.

Use the build- prefix to call the API helper to build the transaction. If this prefix is not set then the command will perform the following steps:

  • call timestamp build-timestampHashes to build an unsigned transaction.
  • call compute signTransaction to sign the transaction with the user defined in using user.
  • call timestamp sendSignedTransaction to send the transaction signed.
  • call view transactionInfo to see relevant data for this transaction.

Params:

  • data (optional): JSON data to timestamp. By default it creates random data.

Examples:

  • timestamp timestampHashes
  • timestamp timestampHashes {"data":"my data"}

timestamp sendSignedTransaction <unsignedTransaction> <signedTransaction>

Command to send a signed transaction to the Timestamp Registry. The JWT is set in the headers. It's also possible to load the parameters from the saved variables by referencing the names.

Params:

  • unsignedTransaction: JSON with the unsigned transaction.
  • signedTransaction: Signed transaction in raw format.

Examples:

  • timestamp sendSignedTransaction {"from":"0x6b...} 0xf9022...
  • timestamp sendSignedTransaction utx sgntx

Track and Trace API​

tnt get <url>

Command to make http GET calls to Track and Trace API. All endpoints are open to the public.

Params:

  • url: Path to get.

Examples:

  • tnt get /documents
  • tnt get /documents/0x12ab...
  • tnt head /accesses?creator=did:ebsi:zkqR9GCLrLYbkubAjuqQZAz

tnt head <url>

Command to make http HEAD calls to Track and Trace API. It is used to check if a DID is authorised to create documents.

Params:

  • url: Path for head.

Example:

  • tnt head /accesses?creator=did:ebsi:zkqR9GCLrLYbkubAjuqQZAz

tnt authoriseDid <senderDid> <authorisedDid> <whiteList>

Command to authorise a new DID to create documents in Track and Trace. This operation is restricted to Support Office and other admins in the allowlist. This operation requires an access token with tnt_authorise scope.

Params:

  • senderDid: DID of the authoriser.
  • authorisedDid: DID of the new entity to be registered.
  • whiteList: Boolean defining if the entity is authorised or not.

Example:

  • tnt authoriseDid did:ebsi:zkqR9GCLrLYbkubAjuqQZAz did:ebsi:znbuGDt6tEqpGZNAuGc2uvZ true

tnt createDocument <documentHash> <documentMetadata> <creator> <timestamp> <timestampProof>

Command to create a new document in Track and Trace. This operation requires an access token with tnt_create scope.

Params:

  • documentHash: Document hash.
  • documentMetadata: Document metadata.
  • creator: DID of the creator.
  • timestamp (optional): External timestamp. By default it uses the timestamp from the blockchain
  • timestampProof (optional): Proof for the external timestamp. By default it uses the block number from the blockchain.

Examples:

  • tnt createDocument 0x29210da926cbf151a09e1c4f8eb9e5c55836016260f5cfa1e2c8c184c6e1943c my-metadata did:ebsi:zkqR9GCLrLYbkubAjuqQZAz
  • tnt createDocument 0x29210da926cbf151a09e1c4f8eb9e5c55836016260f5cfa1e2c8c184c6e1943c my-metadata did:ebsi:zkqR9GCLrLYbkubAjuqQZAz 2024-01-01 0xae3e3d2c20698c1ebf7888b3c965cf1f30834307b7396b966c9abc11996e13ef

tnt removeDocument <documentHash>

Command to remove a document from Track and Trace. This operation must be done by the creator of the document and requires an access token with tnt_write scope.

Params:

  • documentHash: Document hash.

Example:

  • tnt removeDocument 0x29210da926cbf151a09e1c4f8eb9e5c55836016260f5cfa1e2c8c184c6e1943c

tnt grantAccess <documentHash> <grantedBy> subject> <permission>

Command to grant write or delegate access to other DIDs. This operation requires an access token with tnt_write scope. The "delegate" permission can be granted only by the creator of the document. And the "write" permission can be granted by the creator or by accounts with "delegate" permission.

Params:

  • documentHash: Document hash.
  • grantedBy: DID that grants the permission.
  • subject: DID that receives the permission.
  • permission: It should be "write" (to write events) or "delegate" (to be able to grant write access to other DIDs)

Examples:

  • tnt grantAccess 0x29210da926cbf151a09e1c4f8eb9e5c55836016260f5cfa1e2c8c184c6e1943c did:ebsi:zkqR9GCLrLYbkubAjuqQZAz did:ebsi:znbuGDt6tEqpGZNAuGc2uvZ write
  • tnt grantAccess 0x29210da926cbf151a09e1c4f8eb9e5c55836016260f5cfa1e2c8c184c6e1943c did:ebsi:zkqR9GCLrLYbkubAjuqQZAz did:key:z2dmzD81cgPx8Vki7JbuuMmFYrWPgYoytykUZ3eyqht1j9KbqS4dNpBRgwn9zaxGz7jY78W4oFkooFwjY1pCFKhUD1xHzawy4g5H2665VZ3onWGWu1xD6MjGR72EP3WrQkSWXgu2ZfGjGngQuefxpMqrYPGX5U8eFHxj6baBE3neZLqyrL delegate

tnt revokeAccess <documentHash> <revokedBy> subject> <permission>

Command to revoke access to an account for a particular document. The revocation must be done by the account granted it in the first place or by the creator of the document. This operation requires an access token with tnt_write scope.

Params:

  • documentHash: Document hash.
  • revokedBy: DID that grants the permission.
  • subject: DID that receives the permission.
  • permission: It should be "write" (to write events) or "delegate" (to be able to grant write access to other DIDs)

Example:

  • tnt revokeAccess 0x29210da926cbf151a09e1c4f8eb9e5c55836016260f5cfa1e2c8c184c6e1943c did:ebsi:zkqR9GCLrLYbkubAjuqQZAz did:ebsi:znbuGDt6tEqpGZNAuGc2uvZ write

tnt writeEvent <documentHash> <externalHash> <sender> <origin> <metadata> <timestamp> <timestampProof>

Command to write an event in a document. The sender must have the "write" permission and requires an access token with tnt_write scope.

Params:

  • documentHash: Document hash.
  • externalHash: External hash.
  • sender: DID submitting the event.
  • origin: company name or point to other event.
  • metadata: Event metadata.
  • timestamp (optional): External timestamp. By default it uses the timestamp from the blockchain
  • timestampProof (optional): Proof for the external timestamp. By default it uses the block number from the blockchain.

Examples:

  • tnt writeEvent 0x29210da926cbf151a09e1c4f8eb9e5c55836016260f5cfa1e2c8c184c6e1943c 0x9265031a923088137405ffc270a56bf2d4df87495eada46257352356071b009e did:ebsi:zkqR9GCLrLYbkubAjuqQZAz my-origin my-metadata
  • tnt writeEvent 0x29210da926cbf151a09e1c4f8eb9e5c55836016260f5cfa1e2c8c184c6e1943c 0x9265031a923088137405ffc270a56bf2d4df87495eada46257352356071b009e did:ebsi:zkqR9GCLrLYbkubAjuqQZAz my-origin my-metadata 2024-01-01 0xae3e3d2c20698c1ebf7888b3c965cf1f30834307b7396b966c9abc11996e13ef

Trusted Apps Registry API​

tar get <url>

Command to GET in the Trusted Apps Registry API. All endpoints are open to the public.

Params:

  • url: Path to get.

Examples:

  • tar get /apps
  • tar get /apps?public_key_id=0x3f...
  • tar get /apps/ledger-api/authorizations?requesterApplicationId=0x45...
  • tar get /policies

tar (build-)insertAuthorization <appName> <authorizedAppName> <issuer> <status>

Command to insert a new authorization. The JWT is set in the headers. This method requires admin rights in the Trusted Apps Registry.

Use the build- prefix to call the API helper to build the transaction. If this prefix is not set then the command will perform the following steps:

  • call tar build-insertAuthorization to build an unsigned transaction.
  • call compute signTransaction to sign the transaction with the user defined in using user.
  • call tar sendSignedTransaction to send the transaction signed.
  • call view transactionInfo to see relevant data for this transaction.

Params:

  • appName: Resource application name.
  • authorizedAppName: Application that will have access to the resource application.
  • issuer (optional): DID of the issuer. By default it takes the DID defined in using user.
  • status (optional): Status. It must be 1 (default), 2, or 3 which corresponds with active, revoked, or suspended respectively.

Examples:

  • tar insertAuthorization ledger-api my-app
  • tar insertAuthorization ledger-api my-app did:ebsi:zkqR9GCLrLYbkubAjuqQZAz 1

tar (build-)updateAuthorization <id> <status>

Command to update an authorization. The JWT is set in the headers. This method requires admin rights in the Trusted Apps Registry.

Use the build- prefix to call the API helper to build the transaction. If this prefix is not set then the command will perform the following steps:

  • call tar build-updateAuthorization to build an unsigned transaction.
  • call compute signTransaction to sign the transaction with the user defined in using user.
  • call tar sendSignedTransaction to send the transaction signed.
  • call view transactionInfo to see relevant data for this transaction.

Params:

  • id: Authorization ID.
  • status (optional): Status. It must be 1 (default), 2, or 3 which corresponds with active, revoked, or suspended respectively.

Examples:

  • tar updateAuthorization 0x12...4f
  • tar updateAuthorization 0x12...4f 1

tar (build-)insertApp <name> <appAdministrator>

Command to insert a new app in the Trusted Apps Registry. The JWT is set in the headers. This method requires admin rights in the Trusted Apps Registry.

Use the build- prefix to call the API helper to build the transaction. If this prefix is not set then the command will perform the following steps:

  • call tar build-insertApp to build an unsigned transaction.
  • call compute signTransaction to sign the transaction with the user defined in using user.
  • call tar sendSignedTransaction to send the transaction signed.
  • call view transactionInfo to see relevant data for this transaction.

Params:

  • name: Name of the new app.
  • appAdministrator (optional): Did of app administrator. By default it takes the did defined in the command using user.

Examples:

  • tar insertApp my-app did:ebsi:znbuGDt6tEqpGZNAuGc2uvZ

tar (build-)updateApp <id> <domain>

Command to update an existing app. The JWT is set in the headers. This method requires admin rights in the Trusted Apps Registry.

Use the build- prefix to call the API helper to build the transaction. If this prefix is not set then the command will perform the following steps:

  • call tar build-updateApp to build an unsigned transaction.
  • call compute signTransaction to sign the transaction with the user defined in using user.
  • call tar sendSignedTransaction to send the transaction signed.
  • call view transactionInfo to see relevant data for this transaction.

Params:

  • id: Application ID
  • domain: New domain. It must be 1 (default) or 2, which corresponds with "ebsi" and "external" respectively.

Examples:

  • tar updateApp 0x123...fe5 2

tar (build-)insertAppInfo <id> <info>

Command to insert info in an existing app. The JWT is set in the headers. This method requires admin rights in the Trusted Apps Registry.

Use the build- prefix to call the API helper to build the transaction. If this prefix is not set then the command will perform the following steps:

  • call tar build-insertAppInfo to build an unsigned transaction.
  • call compute signTransaction to sign the transaction with the user defined in using user.
  • call tar sendSignedTransaction to send the transaction signed.
  • call view transactionInfo to see relevant data for this transaction.

Params:

  • id: Application ID
  • info: JSON info.

Examples:

  • tar insertAppInfo 0x123...fe5 {"name":"my app"}

tar (build-)insertAppPublicKey <id> <publicKey> <status>

Command to insert a new public key in an app. The JWT is set in the headers. This method requires admin rights in the Trusted Apps Registry.

Use the build- prefix to call the API helper to build the transaction. If this prefix is not set then the command will perform the following steps:

  • call tar build-insertAppPublicKey to build an unsigned transaction.
  • call compute signTransaction to sign the transaction with the user defined in using user.
  • call tar sendSignedTransaction to send the transaction signed.
  • call view transactionInfo to see relevant data for this transaction.

Params:

  • id: Application ID
  • publicKey: Public key. Insert base64 representation of PEM string.
  • status (optional): Status. It must be 1 (default), 2, or 3 which corresponds with active, revoked, or suspended respectively.

Examples:

  • tar insertAppPublicKey LS0tLS1...
  • tar insertAppPublicKey LS0tLS1... 1

tar (build-)updateAppPublicKey <id> <status>

Command to update an existing public key. The JWT is set in the headers. This method requires admin rights in the Trusted Apps Registry.

Use the build- prefix to call the API helper to build the transaction. If this prefix is not set then the command will perform the following steps:

  • call tar build-updateAppPublicKey to build an unsigned transaction.
  • call compute signTransaction to sign the transaction with the user defined in using user.
  • call tar sendSignedTransaction to send the transaction signed.
  • call view transactionInfo to see relevant data for this transaction.

Params:

  • id: Public key ID
  • status (optional): Status. It must be 1 (default), 2, or 3 which corresponds with active, revoked, or suspended respectively.

Examples:

  • tar updateAppPublicKey 0x45...f1 1

tar (build-)insertAppAdministrator <id> <didAdmin>

Command to insert an app administrator to an existing app. The JWT is set in the headers. This method requires admin rights in the Trusted Apps Registry.

Use the build- prefix to call the API helper to build the transaction. If this prefix is not set then the command will perform the following steps:

  • call tar build-insertAppAdministrator to build an unsigned transaction.
  • call compute signTransaction to sign the transaction with the user defined in using user.
  • call tar sendSignedTransaction to send the transaction signed.
  • call view transactionInfo to see relevant data for this transaction.

Params:

  • id: Application ID.
  • didAdmin: DID of new app admin.

Examples:

  • tar insertAppAdministrator 0x45...f1 did:ebsi:zkqR9GCLrLYbkubAjuqQZAz

tar (build-)deleteAppAdministrator <id> <didAdmin>

Command to delete an app administrator from an existing app. The JWT is set in the headers. This method requires admin rights in the Trusted Apps Registry.

Use the build- prefix to call the API helper to build the transaction. If this prefix is not set then the command will perform the following steps:

  • call tar build-deleteAppAdministrator to build an unsigned transaction.
  • call compute signTransaction to sign the transaction with the user defined in using user.
  • call tar sendSignedTransaction to send the transaction signed.
  • call view transactionInfo to see relevant data for this transaction.

Params:

  • id: Application ID.
  • didAdmin: DID to delete from app admins.

Examples:

  • tar deleteAppAdministrator 0x45...f1 did:ebsi:zkqR9GCLrLYbkubAjuqQZAz

tar (build-)insertRevocation <id> <revokedBy> <notBefore>

Command to revoke an app. It will be moved to the revocation list. The JWT is set in the headers. This method requires admin rights in the Trusted Apps Registry.

Use the build- prefix to call the API helper to build the transaction. If this prefix is not set then the command will perform the following steps:

  • call tar build-insertRevocation to build an unsigned transaction.
  • call compute signTransaction to sign the transaction with the user defined in using user.
  • call tar sendSignedTransaction to send the transaction signed.
  • call view transactionInfo to see relevant data for this transaction.

Params:

  • id: Application ID.
  • revokedBy: DID of the admin performing the revocation.
  • notBefore (optional): Point in time when the app becomes revoked. It should be defined in epoch time. By default it takes the actual time.

Examples:

  • tar insertRevocation 0x45...f1 did:ebsi:zkqR9GCLrLYbkubAjuqQZAz
  • tar insertRevocation 0x45...f1 did:ebsi:zkqR9GCLrLYbkubAjuqQZAz 1625568669

tar sendSignedTransaction <unsignedTransaction> <signedTransaction>

Command to send a signed transaction to the Trusted Apps Registry. The JWT is set in the headers. It's also possible to load the parameters from the saved variables by referencing the names.

Params:

  • unsignedTransaction: JSON with the unsigned transaction.
  • signedTransaction: Signed transaction in raw format.

Examples:

  • tar sendSignedTransaction {"from":"0x6b...} 0xf9022...
  • tar sendSignedTransaction utx sgntx

Trusted Issuers Registry API​

OpenAPI documentation

tir get <url>

Command to GET in the Trusted Issuers Registry API.

Params:

  • url: Path to get.

Examples:

  • tir get /issuers
  • tir get /issuers/did:ebsi:12a...

tir (build-)setAttributeMetadata <did> <attributeId> <issuerType> <tao> <taoAttributeId>

Command to pre-register a new issuer in the registry. The JWT is set in the headers. This method requires trust chain rights in the Trusted Issuers Registry.

Use the build- prefix to call the API helper to build the transaction. If this prefix is not set then the command will perform the following steps:

  • call tir build-insertIssuer to build an unsigned transaction.
  • call compute signTransaction to sign the transaction with the user defined in using user.
  • call tir sendSignedTransaction to send the transaction signed.
  • call view transactionInfo to see relevant data for this transaction.

Params:

  • did: DID of the new issuer.
  • attributeId: New attribute ID.
  • issuerType: Issuer type. It must be ti, tao, roottao, or revoked.
  • tao: DID of the parent issuer.
  • taoAttributeId: Attribute ID that accredits the issuer parent as TAO.

tir (build-)setAttributeData <did> <attributeId> <attribute>

Command to register a verifiable credential new issuer in the registry. The JWT is set in the headers. This method requires trust chain rights in the Trusted Issuers Registry.

Use the build- prefix to call the API helper to build the transaction. If this prefix is not set then the command will perform the following steps:

  • call tir build-insertIssuer to build an unsigned transaction.
  • call compute signTransaction to sign the transaction with the user defined in using user.
  • call tir sendSignedTransaction to send the transaction signed.
  • call view transactionInfo to see relevant data for this transaction.

Params:

  • did: DID of the issuer.
  • attributeId: Attribute ID.
  • attribute: Verifiable credential in JWT.

tir (build-)addIssuerProxy <did> <proxyData>

Command to register an issuer proxy. This proxy must be up and running and reply VCs with StatusList2021. Use the (build-) prefix to just call the API helper without signing the transaction.

Params:

  • did: DID of the issuer.
  • proxyData: JSON object containing the proxy data.

Examples:

  • tir addIssuerProxy user.did {"prefix": "https://example.com/my-provider/revocation","headers":{"Authorization": "Bearer ABC"}, "testSuffix": "/credentials/status/1"}

tir (build-)updateIssuerProxy <did> <proxyId> <proxyData>

Command to update an issuer proxy. This proxy must be up and running and reply VCs with StatusList2021. Use the (build-) prefix to just call the API helper without signing the transaction.

Params:

  • did: DID of the issuer.
  • proxyId: Proxy ID to update.
  • proxyData: JSON object containing the proxy data.

tir sendSignedTransaction <unsignedTransaction> <signedTransaction>

Command to send a signed transaction to the Trusted Issuers Registry. The JWT is set in the headers. It's also possible to load the parameters from the saved variables by referencing the names.

Params:

  • unsignedTransaction: JSON with the unsigned transaction.
  • signedTransaction: Signed transaction in raw format.

Examples:

  • tir sendSignedTransaction {"from":"0x6b...} 0xf9022...
  • tir sendSignedTransaction utx sgntx

Trusted Schemas Registry API​

OpenAPI documentation

tsr get <url>

Command to GET in the Trusted Schemas Registry API.

Params:

  • url: Path to get.

Examples:

  • tsr get /schemas
  • tsr get /schemas/0x12f...

tsr (build-)insertSchema <schema> <metadata>

Command to insert a new schema. The JWT is set in the headers. This method requires admin rights in the Trusted Schemas Registry. The schema id is computed based on the schema (see schema lifecycle).

Use the build- prefix to call the API helper to build the transaction. If this prefix is not set then the command will perform the following steps:

  • call tsr build-insertSchema to build an unsigned transaction.
  • call compute signTransaction to sign the transaction with the user defined in using user.
  • call tsr sendSignedTransaction to send the transaction signed.
  • call view transactionInfo to see relevant data for this transaction.

Params:

  • schema (optional): JSON schema. By default it uses a random schema.
  • metadata (optional): JSON metadata. By default is uses random metadata.

Examples:

  • tsr insertSchema
  • tsr insertSchema {"@context":"ebsi.eu","type":"schema"} {"metadata":"data"}

tsr (build-)updateSchema <schemaId> <schema> <metadata>

Command to update an schema. The JWT is set in the headers. This method requires admin rights in the Trusted Schemas Registry.

Use the build- prefix to call the API helper to build the transaction. If this prefix is not set then the command will perform the following steps:

  • call tsr build-updateSchema to build an unsigned transaction.
  • call compute signTransaction to sign the transaction with the user defined in using user.
  • call tsr sendSignedTransaction to send the transaction signed.
  • call view transactionInfo to see relevant data for this transaction.

Params:

  • schemaId: Schema ID.
  • schema (optional): JSON schema. By default it uses a random schema.
  • metadata (optional): JSON metadata. By default is uses random metadata.

Examples:

  • tsr updateSchema
  • tsr updateSchema 0x12f... {"@context":"ebsi.eu","type":"schema"} {"metadata":"data"}

tsr sendSignedTransaction <unsignedTransaction> <signedTransaction>

Command to send a signed transaction to the Trusted Schemas Registry. The JWT is set in the headers. It's also possible to load the parameters from the saved variables by referencing the names.

Params:

  • unsignedTransaction: JSON with the unsigned transaction.
  • signedTransaction: Signed transaction in raw format.

Examples:

  • tsr sendSignedTransaction {"from":"0x6b...} 0xf9022...
  • tsr sendSignedTransaction utx sgntx