DEPRECATED: V1 CrefoTrust API
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
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]