V2 to V3 API Changes

The changes from V2 to V3 of the public CrefoTrust API

Benefits of the new version / Changes

New Accepted ID Methods: Nect

Nect is a state-of-the-art AI-based technology, with which your end-users can identify themselves in minutes. Used by insurance companies, banks and the German government, the solution is very well received by customers thanks to its user-friendliness and cost-efficiency. Contact us for additional information: kontakt@crefotrust.de

Verifier ID

When interacting with the CrefoTrust API the verifierId can be provided as an HTTP header (key: x-verifier-id) instead as part of the request body.

Consider the request body approach as deprecated. Future versions might remove it completely.

Verifier References

The verifierRef object extends the options object when creating an order and gives you the opportunity to pass additional and (almost) arbitrary reference information for the identification case at hand.

The verifierRef object will be passed back to you unchanged on all possible occasions (e.g.: order response, webhook request, order status response). Making it easier to trace the business case through your systems.

There are certain limitations regarding the content of verifierRef though; consult to the docs for the details.

Credential Meta Data

As part of the web hook request, there will be a new root-level property with the name “meta”. Inside the data structure is mirrored, providing the following meta data regarding each verifiable credential:

  • issuedAt: indicating when the credential was provided to the customer
  • issuer: indicating who gave the credential to the customer. This is usually CrefoTrust. There is one exception though: in case the customer authenticated herself with a passport (which doesn’t contain a residential address) the customer provides the address herself and therefor becomes the “issuer” of the “address-credential”.
  • status: containing an URL that can be called to query the current status of the credential in question. It returns “VALID” or “REVOKED”

authorizedRepresentative Credential

This credential is now explicitly defined. Beforehand the relationship between an organization and a person was implicitly given by the fact, that the webhook request was actually made and contained a person and a company. Since the whole point of the order was to identify an authorized representative for a company.

In the future we plan to model different relationships between a company and a person and therefor making this special relationship explicit to make room for extensions.

The authorizedRepresentative credential is requested via the order with:

{
...
  "requiredCredentials": {
    "authorizedRepresentative": true
  }
...
}

and returned in the webhook request in very much the same way:

{
...
  "authorizedRepresentative": true
...
}

In the webhook requests new “meta” section, the authorizedRepresentative credential is present as well. But besides the common properties it additionally holds an “org” and a “person” field with the DID of the company and the person being the participants of the relationship.

Data mocking and testing

Attention: This is an experimental feature and will possibly change in the future.

Testing the CrefoTrust System is currently possible via configurable mock cases. The supported cases are predefined and described below and may also change over time. Each mock case stands for a specific combination of requested and verified person and company data. It also defines the outcome (e.g. success or failure). To test your implemented CrefoTrust integration properly you can configure the mock case in the order attribute verifierRef (see above). The possible configuration parameters are:

  • enableMock: “true” / “false”
  • mockCaseId: “0” / “1” / …
  • mockVariant: “0” / “1” / …

Below the different mock case ids with different variants are shown. Each mock case representents a different person idenfitifaction scenario. The listed names all belong to the company AutoIdent VideoIdent Testcase GmbH and can be selected in the app via the company search bar:

  • Case 0: Success case, positive identification

    Variant 0: Knut Küste
Variant 1: Erika Mustermann
Variant 2: Max Mustermann (not authorized representative; not listed)
Variant 3: Knut Küste (Passport)
Variant 4: Erika Mustermann (Passport)

  • Case 1: Success case, positive identification, input person mismatches output person, output person is also authorized representative

    Variant 0: Paul Mustermann
Variant 1: Paul Mustermann (Passport)

  • Case 2: Success case, positive identification, middle names

    Variant 0: Erika Mustermann
Variant 7: Erika Mustermann (Passport)

  • Case 3: Failure case, positive identification, identification document has expired

    Variant 0: Expiry Mustermann
Variant 1: Expiry Mustermann (Passport)

  • Case 4: Failure case, negative identification (different failure reasons)

    Variant 0: Mallory Mustermann
Variant 1: Mallory Mustermann
Variant 2: Mallory Mustermann

  • Case 5: Failure case, negative identification, process was cancelled by user

    Variant 0: Knut Küste
Variant 1: Paul Mustermann
Variant 2: Mallory Mustermann
Variant 3: Expiry Mustermann
Variant 4: Erika Mustermann
Variant 5: Erika Sophie Mustermann