The following steps explain how to become operational as a Trusted Accreditation Organisation (TAO).
A TAO governs an accredited segment on behalf of the RTAO. It may:
- Accredit itself to issue domain-specific Verifiable Credentials
- Accredit any legal entity to govern or issue domain-specific Verifiable Credentials
- Revoke accreditation from a legal entity that was accredited by the TAO
1 - Create your DID and obtain Verifiable Authorisation to Onboard
To be able to insert transactions into EBSI's underlying ledger, the Legal Entity must possess a valid Verifiable Credential for the given purpose.
In the case of a TAO, a Verifiable Authorisation to Onboard is required to be able to register a new DID into the DID Registry. Follow the steps below to obtain a Verifiable Authorisation to Onboard.
Step 1. Get authorised to request Verifiable Authorisation to Onboard
Before you can request a Verifiable Authorisation to Onboard, some preliminary requirements must be met before you can submit the request.
These requirements include setting up your Organisation Wallet and creating a DID and DID document. Let's take a closer look at each of these steps below.
Step 1.1. Set up your Organisation Wallet with required capabilities
An Organisation Wallet is a digital wallet controlled by your organisation and used to accredit and authorise other organisations. It is important to set up your wallet in order to gain access to the core services offered by EBSI.
You can use the 'Find your wallet' tool to help you find an EBSI Conformant Wallet that best suits the needs of your organisation.
Remember to tick the Accredit and Authorise capability as this capability is required for TAOs. Other features are optional.
If an existing EBSI Conformant Wallet is chosen, the technical onboarding steps detailed below may be different, depending on the user experience provided by the Wallet.
Step 1.2. Create DID and DID document
Decentralised identifiers (DIDs) are URL-based identifiers representing a specific entity. These identifiers are associated with a DID document containing information related to a specific DID, such as the associated repository and public-key information.
The DID and DID document of a TAO are self-generated and must follow the DID Method for Legal Entities. EBSI defines the following DID schema: did:ebsi. Be aware that the DID document must contain an ES256K cryptographic key pair.
Need a quick refresher on DIDs and DID documents? Check out Chapter 3: Decentralised Identifiers (DID) Methods of our Verifiable Credentials Explained series and also feel free to consult as well the DID method for legal entities specifications.
Step 2. Request a Verifiable Authorisation to Onboard
To receive a Verifiable Authorisation to Onboard, Legal Entities must submit a request to their TAO or Root TAO, as it must be issued by the existing Trust Chain members.
The business requirement must be agreed upon by all parties involved to ensure the security and integrity of the onboarding process.
2 - Register your DID document (and DID keys) in the EBSI DID Registry
How to generate a DID document Not sure about how a DID document looks like or how can you generate one? Consult our Legal Entity DID Resolver library.
Now that you have received a Verifiable Authorisation to Onboard, you can proceed to request the access tokens needed to register your DID document and DID keys to the EBSI DID Registry and add a verification method for verification relationships.
Step 1. Get didr_invite access token to write to the DID registry
To request a didr_invite access token, you need to present the Verifiable Authorisation to Onboard to the EBSI Authorisation API with the openid didr_invite scope.
Follow this sequence of API calls to request a didr_invite access token:
- GET Presentation definition: Begin by fetching the presentation definition for the
didr_invitescope. - POST Token Endpoint: Create and submit a presentation according to the fetched definition that contains the Verifiable Authorisation to Onboard.
For further details, please consult our 'How to obtain an access token' guide
Upon successful submission, the EBSI Authorisation API will issue a short-lived, OAuth 2.0 compatible didr_invite access token.
Step 2. Insert a DID document into the DID registry
Insert the DID document and its ES256K key by making a call to the JSON-RPC API using the insertDidDocument method. This action creates a DID document containing default values and assigns the ES256K key with the capability to sign Verifiable Presentation Tokens and ID Tokens.
The following endpoint must be used to insert the DID document:
For further details, please consult our ' How to obtain an access token' guide.
When performed successfully, the Organisation Wallet will receive an Ethereum transaction to be signed. Once the transaction is signed, it is ready to be sent using the sendSignedTransaction method, which will update the ledger with the transaction.
The following endpoint must be used to send a signed transaction:
Step 3. Get a didr_write access token to register your Verification Method and Verification Relationships to the DID Registry
Now you are ready to request a didr_write access token with the openid didr_write scope. It is now not required to present your Verifiable Authorisation to Onboard now that your DID has been onboarded.
Follow this sequence of API calls to request a didr_write access token:
- GET Presentation definition: Begin by fetching the presentation definition for the
didr_writescope. - POST Token Endpoint: Create and submit a presentation according to the fetched definition.
For further details, please consult our ' How to obtain an access token' guide.
Upon successful submission, the EBSI Authorisation API will issue a short-lived, OAuth 2.0 compatible didr_invite access token.
Step 4. Add a verification method and verification relationships to your DID document
Since EBSI requires ES256 keys for signing Verifiable Credentials, you need to use the didr_write access token to add this key in the form of a new verification method with additional verification relationships to complete the DID document.
Note: It will be necessary to perform the process below three times. This means there will be three transactions in total, one for each of the following methods:
- addVerificationMethod - this method will add the ES256 key to the DID document
- addVerificationRelationship - this adds the "authentication" verification relationship for the ES256 key
- addVerificationRelationship - this adds the "assertionMethod" for the ES256 key
The following endpoints must be used to add the verification methods and verification relationships:
Please note that this verification method will only appear in the DID document after adding a verification relationship.
Upon successful submission, your wallet will receive an HTTP 200 transaction from the EBSI DID Registry Service to be signed. Once the transaction is signed, it is then ready to be returned using the sendSignedTransaction method, which will update the ledger with the transaction.
The following endpoint must be used to send a signed transaction:
After you have completed all three transactions, you can verify if the DID registration was successful by calling the Get DID document endpoint.
3 - Obtain and register Verifiable Accreditation to Accredit in the Trusted Issuer Registry
The Trusted Issuers Registry (TIR) is a registry containing a list of Legal Entities that are authorised to issue certain types of credentials.
After you have received the Verifiable Accreditation to Accredit, you must complete the invitation by registering the credential into the Trusted Issuers Registry. The following steps will guide you through this process.
Step 1. Request Verifiable Accreditation To Accredit
To receive an invitation from the EBSI Credential Issuer, you must first request a VerifiableAccreditationToAccredit Verifiable Credential.
The Credential Issuer will then invite you to join the Trust Chain, reserving a location and issuing the VerifiableAccreditationToAccredit for that specific location.
Step 2. Obtain tir_invite access token from the Authorisation API to write into the Trusted Issuers Registry
To request a tir_invite access token, you need to present proof of ownership of your Verifiable Accreditation to Accredit to the EBSI Authorisation API.
Follow this sequence of API calls to request a tir_invite access token:
- GET Presentation definition: Begin by fetching the presentation definition for the tir_invite scope.
- POST Token Endpoint: Create and submit a presentation according to the fetched definition that contains proof of ownership of your Verifiable Accreditation to Accredit
For further details, please consult our ' How to obtain an access token' guide.
Upon successful submission, the EBSI Authorisation API will issue a short-lived, OAuth 2.0 compatible tir_invite access token.
Step 3. Register your Verifiable Accreditation to Accredit
The invitation is accepted by registering your Verifiable Accreditation to Accredit into the Trusted Issuers Registry.
The Verifiable Authorisation has a reservedAttributeId that defines the location where the authorisation must be registered into. You should build a setAttributeData transaction with attributeId from reservedAttributeId.
The following endpoint must be used to register your Verifiable Accreditation to Accredit into the TIR:
- TIR JSON RPC - setAttributeData: Begin by fetching the presentation definition for the tir_invite scope.
Upon successful submission, your wallet will receive an HTTP 200 transaction from the EBSI TIR Service to be signed. Once the transaction is signed, it is then ready to be returned using the sendSignedTransaction method, which will update the ledger with the transaction.
The following endpoint must be used to send a signed transaction:
After the transaction has been completed, you are officially onboarded as a TAO. Congratulations! 👏
4 - Start issuing Verifiable Credentials
You are almost ready to start issuing Verifiable Credentials. Just a few more steps to go!
Verifiable Credential and Presentation
Check out our VC and VP library to create and verify EBSI-compliant W3C Verifiable Credentials and Verifiable Presentations in JWT format
Step 1. Authorise TAO/TI to onboard by issuing a V. Authorisation to Onboard
Step 1.1. Provide Authorisation Server to authenticate TAO/TI
Now that you have set up your Root Trusted Accreditation Organisation, you can onboard Trusted Accreditation Organisations and Trusted Issuers.
Your Root TAO needs to provide an OIDC Authorisation Server for TAO/TI. Authentication can be performed by using a code flow or by pre-authorisation.
Step 1.2. Authentication code flow
For authentication and authorisation, the Root TAO needs to provide an Authorisation Server. The TAO/TI can start authentication by calling the Authorisation Server's authorise endpoint with response_type code. In response, the Authorisation Server should proceed to authenticate the TAO/TI, for example, by requesting an ID Token. After succesful authentication, the Authorisation Server should respond with a code. Using this code, the TAO/TI can request an access token (by calling the Authorisation Server's token endpoint).
Step 1.3. Authentication with pre-authorisation
In addition to the code flow above, authentication can also be done using a pre-authorised code. This code is deliver to the TAO/TI via a Credential Offering or out of band method. Using this code the TAO/TI can invoke the Authorisation Server's token endpoint directly to get an access token.
Step 1.4. Provide Credential Issuer service for issuing TAO/TI Authorisation to Onboard
The Root TAO needs to provide a Credential Issuer service for a TAO/TI. It should contain a credential endpoint which is protected by requiring an access token issued in the previous phase.
The TAO/TI should use this endpoint to request a Verifiable Authorisation to Onboard credential. Using this credential, the TAO/TI can onboard to EBSI by inserting their DID document into EBSI DID Registry.
Step 2. Start issuing Verifiable Accreditations to TAO and TI
To be able to issue VCs, the TAO needs to add themselves to the EBSI Trusted Issuer Registry. The Root TAO authorises this by issuing a Verifiable Accreditation to Attest.
Step 2.1. Enable TAO Request a V. Accreditation to Attest
Using the Authorisation Server and Credential Issuer service provided by the TAO, the TAO/TI is able to request a Verifiable Accreditation to Attest VC. Using this VC, the TAO/TI can add themselves to the EBSI Trusted Issuers Registry.
Step 2.2. Authorise TAO to accredit other TAO/TI
To be able to accredit other TAO/TIs a TAO needs register in the Trusted Issuers Registry. The TAO authorises this by issuing a Verifiable Accreditation to Accredit VC. Using this VC the TAO can register themselves in the Trusted Issuers Registry.
5 - Revoke a Verifiable Accreditation
The following steps will allow you to revoke a Verifiable Accreditation if you need to.
Step 1. Obtain tir_write access token in Auth API to write to the TIR
To request a tir_write access token, you need to present proof of ownership of your Verifiable Authorisation for Trust Chain to the EBSI Authorisation API with the openid tir_write scope.
Follow this sequence of API calls to request a tir_write access token:
- GET Presentation definition: Begin by fetching the presentation definition for the
tir_writescope. - POST Token Endpoint: Create and submit a presentation according to the fetched definition.
For further details please consult our ' How to obtain an access token' guide.
Step 2. Register the revocation in the Trusted Issuers Registry
Revocation of a Verifiable Accreditation will be done through the Trusted Issuer Registry by the TAO who originally invited the Legal Entity.
The TAO must set the issuerType to revoked to revoke an existing Verifiable Accreditation or the invitation. Verifiable Accreditations must contain credentialStatus with type EbsiAccreditation, where validity is determined by the smart contract.
Use the following endpoint to modify the attribute metadata using the setAttributedata method: