Integration of VIDcredentials
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.
info
The VIDchain support team creates and registers an entity at VIDchain. Please contact support@vidchain.org for creating and registering your entity.
Once the entity is created, an identifier iss
and an apiKey
is issued.
caution
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.
info
VIChain supports the following DID methods such as Ethereum did:ethr
, EBSI did:ebsi
, Alastria did:ala
, and the ledger-less did:key
DID method. In case another DID method is preferred that is not supported yet, please contact support@vidchain.org.
Authenticate towards VIDcredentials​
This section provides information related to this endpoint Login to VIDcredentials API Services.
note
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:
{
"iss": <client-id>,
"aud": "vidchain-api",
"nonce": "z-0427dc2516d0" (random nonce),
"apiKey": <the provided API key>,
"did": <did method>
}
note
The assertion is a JSON encoded in base64
.
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:
grantType
The grant type specifies the grant type of the token, which is defined in our case asurn:ietf:params:oauth:grant-type:jwt-bearer
.scope
The scope describes the scope which is in our casevidchain profile entity
.assertion
The assertion field has to contain as value the previous created assertion asbase64
encoded string.
An example payload that has to be sent to the /api/v1/sessions
endpoint is shown below:
{
"grantType": "urn:ietf:params:oauth:grant-type:jwt-bearer",
"assertion": "eyJpc3MiOiJFeGFtcGxlIFVudmllcnNpdHkiLCJhdWQiOiJ2aWRjaGFpbi1hcGkiLCJub25jZSI6InotMDQyN2RjMTIzNDU2IiwiYXBpS2V5IjoiMTExMTNkZWYtMjIyMi0zMzMzLTQ0NDQtMTIzNDU2Nzg5MCJ9",
"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:
{
"accessToken": "eyJhbGciOiJFUzI1NksiLCJ0eXAiOiJKV1QiLCJraWQiOiJ2aWRjaGFpbi1hcGkifQ.eyJzdWIiOiJFTlRJVFktTkFNRSIsImRpZCI6ImRpZDp2aWQ6MHg3OTc0ZGU2NTY4OEFiNTU0QWZENDk1NWMxMkYzQzk0MjdmM0E4QzFBIiwibm9uY2UiOiJ6LTA0MjdkYzI1MTZkMCIsImlhdCI6MTU5ODAyMjM0MSwiZXhwIjoxNjAwNjE0MzQxLCJhdWQiOiJ2aWRjaGFpbi1hcGkifQ.CbsJxbeMmZj8lS8k_-QH4zPLjvYcWjDDpZ7vrOGFq2R30ZSH4bCoZBz2Ra4LXYMkYjH_jPBikso667baudsI9w",
"tokenType": "Bearer",
"expiresIn": 1600614341,
"issuedAt": 1598022341
}
The bearer token accessToken
needs to be included in request to protected API endpoints.
note
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.
important
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 support@vidchain.org.
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 iconn
.
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>",
"icon": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAgAAAAIACAIAAAB7GkOtAAABfmlDQ1......"
}
VIDchain Integration Examples​
More integration examples can be found on the public GitHub repository demonstrating for example the interaction with VIDconnect or VIDcredentials.