Register your Entity
In order to interact with VIDcredentials you need to register your entity first. An entity represents a party (e.g. organisation) that will be registered at VIDcredentials. This entity will hold the DIDs and the corresponding key material used to issue credentials and will provide access to verification services as well.
The VIDchain support team creates and registers an entity at VIDchain. Please contact email@example.com for creating and registering your entity.
Once the entity is created, an identifier
iss and an
apiKey is issued.
Please note, the api key has to be stored securely to prevent third parties of falsely accessing and issuing credentials.
The DID method
did:ethr is the default selected method for creating the DID. The created DID will be used as issuer DID.
VIChain supports the following DID methods such as Ethereum
did:ala, and the ledger-less
did:key DID method. In case another DID method is preferred that is not supported yet, please contact firstname.lastname@example.org.
Authenticate towards VIDcredentials
This section provides information related to this endpoint Login to VIDcredentials API Services.
VIDcredentials uses the Bearer Token based Http authentication scheme for the client authentication towards the API. All requests to the API must contain the bearer token.
To obtain an access token, first, an assertion has to be created. This assertion contains the attributes to identify your entity. The
assertion is a
base64 encoded JSON and contains the following .
The assertion payload contains the following fields:
iss: The issuer field must contain the OpenID connect client ID to identify the entity on the VIDchain API.
nonce: The nonce field should contain a randomly generated number only used once (nonce).
apiKey: The API key provided by the VIDchain team during the registration has to be included in this field.
callbackUrl: (optional) This callback URL describes the redirect location for VIDchain when finalising an async process like a presentation request. Note that this is not the OIDC callback but the entity backend endpoint where the VIDChain APIs will send back the endpoint where to retrieve the verifiable presentation.
did: This is field is only mandatory when the entity has more than one DID assigned.
See the following example to check the assertion format:
"nonce": "z-0427dc2516d0" (random nonce),
"apiKey": <the provided API key>,
"did": <did method>
The assertion is a JSON encoded in
To receive the bearer token, a
POST request has to be sent to the
/api/v1/sessions endpoint. The request must contain the following attributes:
grantTypeThe grant type specifies the grant type of the token, which is defined in our case as
scopeThe scope describes the scope which is in our case
vidchain profile entity.
assertionThe assertion field has to contain as value the previous created assertion as
An example payload that has to be sent to the
/api/v1/sessions endpoint is shown below:
"scope": "vidchain profile entity"
After performing the POST request, VIDcredentials authenticates your entity and provides the access token required for accessing the endpoints. An example response is shown below:
The bearer token
accessToken needs to be included in request to protected API endpoints.
The bearer token is only valid for 15 minutes and should be refreshed during this time for continuously usage.
Ready to go
Once you know how to get an
accessToken, you are free to start trying out the VIDcredentials service. In the OpenAPIs you will find all the details for issuing and verifying credentials and presentations.
Please note that this authentication method is used for VIDcredentials and eIDAS Bridge. But it is different for VIDconnect. For question regarding the authentication method of VIDconnect, please contact email@example.com.
Modify your Entity (Optional)
Certain attributes of an entity can be changed even after the entity has been created and registered. Particularly, it is possible to change the
callbackURL as well as the entity
callbackUrl: (optional) This callback URL describes the redirect location for VIDchain when finalising an async process like a presentation request. Note that this is not related to VIDconnect callback but the entity backend endpoint where the VIDChain APIs will send back the endpoint where to retrieve the verifiable presentation.
icon: (optional) This field expects the base64 encoded icon that should be displayed in VIDwallet. The app will see this icon in the credentials issued by your entity.
An example call is shown below and the request is authenticated using the bearer token.
- HTTP call:
PUT to https://staging.vidchain.net/api/v1/legal-entities/attributes
- Authorization: Bearer token
- Body :
"callbackUrl: "https://<entity backend url>/<callback path>",
VIDchain Integration Examples
More integration examples can be found on the public GitHub repository demonstrating for example the interaction with VIDconnect or VIDcredentials.