Concepts

Key concepts and terms explanation.

DID

DID (Decentralized Identifiers) is a W3C standard and defines addressable identity documents. Basically an ID, which also holds the information abount where it resides (a web address, a blockchain, …) and where additional information can be gathered. A DID is made up of a three-part string separated by colon, e.g:

did:method:method-specific-identifier

For the web-method specifically the identifier is made up of the domain name, optional path segments (separated by colon) and an ID string, e.g.:

did:web:api.crefotrust.de:user:a1b2c3d4e5f1a1a

For more information visit the DID specs and web-method specs.

We are using the terms “decentralized Identity” and “digital Identity” interchangeably, knowing that these are (arguably slightly) different concepts.

Verifier

The Verifier is the receiver of credentials usually in form of a special presentation, tailored for the purposes of the Verifier. The tailoring happens when the Verifier creates an order with CrefoTrust. And CrefoTrust delivers the credentials’ data to the Verifier in consent of the holder of the Credentials. The presentation the Verifier receives contains meta data, which allows to actually verify the correctness of the information.

The concept of a verifier stems from the official W3C specification and is in the scope of the specification a digital Identity itself.

To allow the integration with external systems that don’t follow the standard, we are interpreting the verifier quite loosely, as a party that has the right to create orders and receive fulfilled orders’ data on user consent.

Holder

The Holder is the digital Identity that has access to a Credential. The Holder is usually, but doesn’t need to be, the Credential’s subject. Meaning that the claim of the Credential is about the Holder himself.

Consider these examples:

  • A digital Identity has control over an “address” Credential whose subject is the same digital Identity. The credential claims that the holder is living at this address.
  • The digital Identiy might also be a holder for a “legalName” Credential of some company. In this credential the subject is the digital Identity of the company. The credential claims the company has the legal name “Such-And-Such Inc.”. And the Holder only controls the credential.

Issuer

On the highest abstraction level an Issuer is a digital identity who has stated something about another digital identity. This something is the Credential. And by creating this credential a digital Identity becomes an issuer.

To get a little bit more specific: the issuer is (usually a trusted) party in the CrefoTrust ecosystem who has the authority to create Credentials that claim something (what that something is is decided by the type of Credential) about a digittal Identity.

Issuers usually fall back to some data source to base their claims upon. Like CrefoTrust uses the information, that is collected during the Nect or IDnow identification processes, to create name, address and birthday credentials.

Credential

In the CrefoTrust context, a credential is basically a concise information package. Whose parts are semantically close and have a similar lifetime/change rate. It encapsulate either facts about a single natural or legal person (a company) or facts about relationships between people and companies. Furthermore each has differing levels of assurance, depending on the facts origin and implicitely on it’s collection method.

A verifiable credential in the meaning of W3C is far more elaborate. For details please refer to the spec.

We are borrowing the (for us) essential parts of the specifications without overcomplicating it.

Wallet (Planned)

A wallet holds the aquired credentials and provides a history of interactions with it.

Account

To access a wallet and the stored information a user needs an account. This is currently just an email address and a password. Other authentication means and sources will be provided in the future.

Order

The order is the central concept to aquire information about a user in the CrefoTrust ecosystem. To get information from someone (regardless if already a CrefoTrust user or not) your first step is to create an order, specifiying what you want to know. In response you will receive an URL, where you have to send your user. And in the end the webhook, configured in this order, will receive the requested information (if the user has consented to share it).

PIN-Order

The pin-order belongs to the pin letters process. It can be seen as a precursor of a “regular” order. When creating a pin-order you must provide the Crefonummer of one or more companies and will receive a ShortCode and PIN for each company. The idea is that you then send a letter or email to a contact person for these companies with these dates. When they later succeed in entering the information correctly on the CrefoTrust pin-entry page (this is when a “normal” order get’s created and the process is completed automatically) we can assume that they have control over the receiving end in some capacity and therefor are agents of that company.

Webhook

An HTTP endpoint, that can be accessed from the CrefoTrust Backend Systems using an HTTP POST call. This endpoint will receive the information that was requested via the corresponing order.

The orderID will be attached as a path element, e.g.: “https://api.my-backend-system.de/webhook/[orderID]”.

If you require to setup authentication, you can provide us with a header name and value, which will be used on every webhook call. At the moment this is a manual setup step. If you want this and/or need to whitelist our IP addresses please feel free to contact us.

Redirect

Provide an object with the URLs your customer will be sent after they finish the CrefoTrust process. One for the positive (success) and one for the negative (failure) case.

Similar to the webhook, the orderID will be added to the provided URLs (as an URL parameter with the name orderId), e.g.: https://www.my-frontend.de/success.html?orderId=[orderID] and https://www.my-frontend.de/error.html?orderId=[orderID]. This can be convenient when you want to send your customer into a tailored process.

ID Methods

ID Methods are (usually) 3rd party services that CrefoTrust uses to collect verified information about a person. ID methods are the source for most person credentials. In the PinLetters process the pin entry acts as an ID method as well. But it only is the source for the CRID credential. Basically just proving that an account exists.

Currently three ID methods of three different ID providers can be used with CrefoTrust. These are:

  • IDNow / ITM - Video Ident; use “itm_videoident” in acceptedIdMethods and/or offeredIdMethods
  • Nect - Auto Ident use “nect_autoident” in acceptedIdMethods and/or offeredIdMethods
  • PinLetter use “pin_letter” in acceptedIdMethods and/or offeredIdMethods. With the PinLetter-Method only a subset of the data can be delivered. For details head over tho the PinLetter page.

Crefonummer

The Crefonummer is a public identifier for companies as well as people. The organization “Creditreform” is responsible for the issuance of Crefonummers. It’s a numeric 10 digit number. In the context of CrefoTrust crefoId, Crefo and Crefonummer are used interchangably.