DEPRECATED: V1 CrefoTrust API

The API documentation of CrefoTrust in version 1

CrefoTrust enables the verification of people and companies.

Features

  • Request multiple Credentials in one call
  • Automatic verification with W3C Standards
  • Destructuring of Verifiable Presentations and Credentials
  • Fully written in Typescript

Install

npm

npm install @crefotrust/sdk

yarn

yarn add @crefotrust/sdk

Interaction between SDK and CrefoTrust Overview

Placeholder

Frontend Usage

In the frontend the call to CrefoTrust is created and executed. Afterwards the response gets verified as an initial feedback for the User. The correct usage also requires an additional verification of the response in a trusted environment such as a backend, because the frontend can of course compromise the verification result.

Import

import { requestCredentials, VCType } from '@crefotrust/sdk';

Setup needed credentials

const requiredCredentials = [
    VCType.NAME, 
    VCType.ADDRESS, 
    VCType.NATIONALITY, 
    VCType.BIRTHDATE, 
    VCType.AUTHORIZEDREPRESENTATIVE
];

!!! note See all currently available credentials

Setup name of your service/application to be displayed on CrefoTrust

const verifierName = "Sea Logistics";

Setup CrefoTrust URL

Should normally be #!js https://app.crefotrust.de. Or for development and testing #!js https://app-demo.crefotrust.de

const crefotrustURL = "https://app.crefotrust.de";

Setup expected Issuer

Should normally be #!js did:web:api.crefotrust.de. Or for development and testing #!js did:web:api-demo.crefotrust.de

const expectedIssuer = "did:web:api.crefotrust.de";

Setup a company crefoId (Optional)

Should you want to preselect a company for the user, you can specifiy a crefoId.

const crefoId = "1234387490";

In this configuration the user can change the company in our process again. To make the company unchangable for the user set a flag.

const crefoIDrequired = true;

Execute the call

Executing the function will return a promise and open a new Window or Tab in the Users browser. After the user completes the verification the windows closes and the promise resolves with already verified credentials.

Errors

Errors always consist of and error code and a message string split with a “,”. The message is only for the developer.
Example error: #!js 10, some error happend

Possible common errors include:
10
Either the user intentionally clicked abort verification, or they closed the window/tab
20
One or more of the verification steps failed, this could mean that user data doesn’t match the data provided by the identity provider or that the video ident failed. This error can possibly be resolved by an admin. So the process can succeed at a later time.
30
Various other erros that are not expected to happen. For the user treat them as if the process doesn’t work currently and investigate. This might be: CT window didn’t open or no jwt send back, but also no error or some other edge case
40
Verification of the VP or included VCs failed. This could mean the user is trying to use an old VC or VP either intentionally or because some process took to long. Or that the VC recieved an update and is no longer valid. In most cases redoing the process will solve the issues.

Promise

requestCredentials(
        requiredCredentials,
        verifierName, 
        crefotrustURL, 
        expectedIssuer
//      crefoId,            // Optional
//      crefoIDrequired,    // Optional    
    )
    .then((result)=>{
        console.log(result);
        // Handle the result
        // Should be send to the backend for additional verification
    })
    .catch((error)=>{
        console.error(error);
        // Handle the error
    })

Async/Await

let result;
try {
    result = await requestCredentials(
        requiredCredentials,
        verifierName, 
        crefotrustURL, 
        expectedIssuer
//      crefoId,            // Optional
//      crefoIDrequired,    // Optional   
    )
} catch (error) {
    console.error(error);
    // Handle the error
}
console.log(result);
// Handle the result
// Should be send to the backend for additional verification

Backend Usage

To make sure that the response are valid credentials send by the CrefoTrust issuer, the JWT that represents the Verifiable Presentation needs to be send to the backend to fully verify it. Currently we only support a Node.js backend. Supporting other stacks is planned for the future.
Using earlier shown code from the frontend:

const result = await requestCredentials(
        requiredCredentials,
        verifierName, 
        crefotrustURL, 
        expectedIssuer
    );

The result contains a #!js jwt field in addition to the the decoded and already processed information. This field is the only relevant one for a secure validation.

const jwt = result.jwt;

Import

=== “Node.js” javascript import { CrefoTrustVCVerifier } from "@crefotrust/sdk";

Setup

First set the expected issuer. Should normally be #!js did:web:api.crefotrust.de. Or for development and testing #!js did:web:api-dev.crefotrust.de

=== “Node.js” javascript const expectedIssuer = "did:web:api.crefotrust.de";

Then call the constructor.

=== “Node.js” javascript const vcVerifier = new CrefoTrustVCVerifier( expectedIssuer );

Verify

Use the verify function to fully verify the #!js JWT that represents the Verifiable Presentation.

Promise

=== “Node.js” javascript vcVerifier.verify(jwt) .then((result)=>{ console.log(result); // Handle the result }) .catch((error)=>{ console.error(error); // Handle the error })

Async/Await

=== “Node.js” javascript let result; try { result = await vcVerifier.verify(jwt) } catch (error) { console.error(error); // Handle the error } console.log(result); // Handle the result

Available Credentials

All current Credentials

Please use the enum to get the correct spelling for the credentials. Any requests with unavailable credentials will be rejected.
The suffix ORG denotes the credential for the company not the person. So ADDRESS is the address of the person and ADDRESSORG is the address of the company or organisation.

enum VCType {
    NAME,
    ADDRESS,
    BIRTHDATE,
    NATIONALITY,
    CRID,
    CREFOID,
    CREFOIDORG,
    LEGALNAME,
    LEGALFORM,
    ADDRESSORG,
    AUTHORIZEDREPRESENTATIVE,
}

Credential Structure

All credentials have the same general structure.

!!! note We will ignore the JWT header and signature.

A general payload looks like this:

{
  iat: 1601536319,
  type: [ "VerifiableCredential", "NationalityCredential" ],
  credentialSubject: {
    id: "did:web:api-dev.crefotrust.de:user:705782e5-40d3-4dfc-a4e3-51bf2eab3ce7",
    nationality: "DE"
  },
  status: {
    id: "https://api-dev.crefotrust.de/api/credentials/73c17770-750a-4d78-83b8-b9c80571a9db/status"
  },
  iss: "did:web:api-dev.crefotrust.de"
}

Depending on the type the #!js type and the structure of the content of #!js credentialSubject will change.

{
  iat: 1601536319,
  type: [ "VerifiableCredential", "NationalityCredential" ],
  credentialSubject: {
    id: "did:web:api-dev.crefotrust.de:user:705782e5-40d3-4dfc-a4e3-51bf2eab3ce7",
    nationality: "DE"
  },
  status: {
    id: "https://api-dev.crefotrust.de/api/credentials/73c17770-750a-4d78-83b8-b9c80571a9db/status"
  },
  iss: "did:web:api-dev.crefotrust.de"
}

Example Credential

An example credential. It is not valid.

Encoded JWT

eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NksifQ.eyJpYXQiOjE2MDM3OTA4NTUsInR5cGUiOlsiVmVyaWZpYWJsZUNyZWRlbnRpYWwiLCJOYXRpb25hbGl0eUNyZWRlbnRpYWwiXSwiY3JlZGVudGlhbFN1YmplY3QiOnsiaWQiOiJkaWQ6d2ViOmFwaS1kZXYuY3JlZm90cnVzdC5kZTp1c2VyOjcwNTc4MmU1LTQwZDMtNGRmYy1hNGUzLTUxYmYyZWFiM2NlNyIsIm5hdGlvbmFsaXR5IjoiREUifSwic3RhdHVzIjp7ImlkIjoiaHR0cHM6Ly9hcGktZGV2LmNyZWZvdHJ1c3QuZGUvYXBpL2NyZWRlbnRpYWxzLzczYzE3NzcwLTc1MGEtNGQ3OC04M2I4LWI5YzgwNTcxYTlkYi9zdGF0dXMifSwiaXNzIjoiZGlkOndlYjphcGktZGV2LmNyZWZvdHJ1c3QuZGUifQ.Y3yeZsBU1Mp05JgGQLDZBFnIoQvcDSyehOYVdWlgkVSABafXI9UwgdoR9LAnj0oT7li6tHQJAqWkl5Aih2RucQ

Decoded JWT

{
    typ: "JWT",
    alg: "ES256K"
}.
{
    iat: 1601536319,
    type: [
        "VerifiableCredential",
        "NationalityCredential"
    ],
    credentialSubject: {
        id: "did:web:api-dev.crefotrust.de:user:705782e5-40d3-4dfc-a4e3-51bf2eab3ce7",
        nationality: "DE"
    },
    status: {
        id: "https://api-dev.crefotrust.de/api/credentials/73c17770-750a-4d78-83b8-b9c80571a9db/status"
    },
    iss: "did:web:api-dev.crefotrust.de"
}.
[signature]