Skip to main content

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 as urn:ietf:params:oauth:grant-type:jwt-bearer.
  • scope The scope describes the scope which is in our case vidchain profile entity.
  • assertion The assertion field has to contain as value the previous created assertion as base64 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.