Terminology
Unum ID uses a few specialized terms and concepts. It's not necessary to understand these in full detail, but knowing a little about them will help you deploy and use Unum ID tech.
tip
We've included helpful tooltips like this one (hover over it) throughout the docs. These offer quick definitions, examples, and links to dive in deeper. Anytime you see an underline, hover over it to see the tooltip!
The tooltips you'll see most often refer to the terms described in this section (for example:
The main terms to know are:
The less important terms are:
When possible, we avoid using these less important terms to make the docs more readable and lighter on jargon.
#
Main Terms#
CredentialA credential is a collection of data about a person. It's issued by a company (i.e. created and sent to a user) and stored in the company's app, on that user's device.
Example: ACME Bank issues a KYC verification credential to Richard (an ACME user). This includes Richard's contact information and account numbers, as well as a level of confidence in the accuracy of the data.
Components: A company issues credentials using the Server SDK, and an app stores credentials using the Mobile SDK.
At a high level, to issue a credential a company inputs four pieces of information (into the Server SDK, which handles the rest):
- type of the credential
- identifier for the person
- data about the person
- identifier for the company
The data can be anything at all (any valid JSON) โ contact information, proof of government ID, medical data, etc.
The credential is cryptographically signed with the company's private key. This makes it possible to later check that the credential is valid and was issued by that company.
The full details of the credential object aren't that important or helpful to know, but here's an example:
#
PresentationA presentation is a set of one or more
A credential is a collection of data about a person. It's issued by a company (i.e. created and sent to a user) and stored in the company's app, on that user's device.+ More...credentials. It's shared with (or presented to) a company by a user.
Example: Richard shares a presentation of a KYC verification credential (which ACME Bank issued to him) with Hooli FinTech.
Components: A user's app shares (or presents) presentations using the Mobile SDK, and a company verifies presentations using the Server SDK.
A user typically (but not always) shares a presentation in response to a
The presentation is cryptographically signed with the user's private key. This makes it possible to later check that the presentation is valid and was created by the user's app, on their device.
note
Each credential within the presentation is itself cryptographically signed but with the private key of the company that issued it. So, for example, a presentation of three credentials has four total signatures: one on each credential and one on the whole presentation.
The full details of the presentation object aren't that important or helpful to know, but here's an example:
#
RequestA request (or presentation request) is a request for a
A presentation is a set of one or more credentials. It's shared with (or presented to) a company by a user.+ More...presentation. It's sent by a company to a user, who chooses whether to share a presentation in response.
Example: Hooli FinTech sends Richard a request for (a presentation of) a KYC verification credential from ACME Bank.
Components: A company creates requests using the Server SDK and routes them to users using the Web SDK. A user's app responds to requests using the Mobile SDK.
At a high level, to create a request a company inputs three pieces of information (into the Server SDK, which handles the rest):
- identifier for the company
and a list containing, for each credential:
- type of the credential
- acceptable An issuer is a role a company can play to issue credentials to subjects (users). An issuer also change credential statuses, for example to revoke credentials.+ More...issuer(s) of the credential
If multiple issuers are listed, a credential (of the correct type) from any one of them is acceptable.
important
The
The request is cryptographically signed with the company's private key. This makes it possible to later check that the request is valid and was created by that company, which helps prevent attacks like phishing.
#
Less Important TermsWhen possible, we avoid using these less important terms to make the docs more readable and lighter on jargon. However, there are cases where it's necessary to use more precise language, so this section serves as a useful reference.
#
IssuerAn issuer is a role a company can play to issue
A credential is a collection of data about a person. It's issued by a company (i.e. created and sent to a user) and stored in the company's app, on that user's device.+ More...credentials to+ More...subjects (users). An issuer can also change credential statuses, for example to revoke credentials.
important
A company can be both an
Example: ACME Bank issues a KYC verification credential to Richard (an ACME user). It later revokes that credential and issues a new one to Richard to update his information.
Components: An issuer issues credentials and changes credential statuses using the Server SDK.
To register an issuer and recieve an issuer API key, a company (already registered as an Unum ID customer) submits to us three pieces of information:
- name (human readable)
- logo icon
- brand colors
These are used in the Mobile SDK and Web SDK to display content to users.
#
Holder AppA holder app is an Unum ID enabled mobile app. See also:
A holder is an instance of a holder app, installed on a particular device. It stores (or holds) credentials for a subject (user). It also allows the subject to respond to requests with presentations.+ More...holder.
Example: ACME Bank adds Unum ID technology to its mobile app, making it a holder app.
Components: A holder app is one using the Mobile SDK.
#
HolderA holder is an instance of a
A holder app is an Unum ID enabled mobile app. See also: holder.+ More...holder app, installed on a particular device. It stores (or holds)A credential is a collection of data about a person. It's issued by a company (i.e. created and sent to a user) and stored in the company's app, on that user's device.+ More...credentials for a+ More...subject (user). It also allows the subject to respond toA request (or presentation request) is a request for a presentation. It's sent by a company to a user, who chooses whether to share a presentation in response.+ More...requests and shareA presentation is a set of one or more credentials. It's shared with (or presented to) a company by a user.+ More...presentations.
note
The definition of a holder includes an app instance on a particular device for two reasons:
- A holder app stores different credentials for different users.
- A user's private keys are stored in the secure hardware of their phone (and never leave that device).
Example: The ACME Bank app (installed on Richard's phone) stores a KYC verification credential for Richard. When Hooli FinTech requests an ACME KYC verification, the app lets Richard respond with a presentation of the KYC verification credential.
Components: A holder app is one using the Mobile SDK, and a holder is an instance of that installed on a particular device.
#
SubjectA subject is a user of a
A holder app is an Unum ID enabled mobile app. See also: holder.+ More...holder app. Each subject uses one or moreA holder is an instance of a holder app, installed on a particular device. It stores (or holds) credentials for a subject (user). It also allows the subject to respond to requests with presentations.+ More...holders.
tip
We use "user" instead of "subject" as much as possible, since these are almost always interchangeable, but you'll see "subject" at the code level (for example in credentialSubject
).
Example: Richard is a subject (user) of the ACME Bank mobile app. He uses two holders: the app installed on his phone and his tablet.
Components: A holder app is one using the Mobile SDK, and a holder is an instance of that installed on a particular device. A subject uses one or more holders.
#
VerifierA verifier is a role a company can play to verify
A presentation is a set of one or more credentials. It's shared with (or presented to) a company by a user.+ More...presentations shared by+ More...subjects (users). A verifier can also makeA request (or presentation request) is a request for a presentation. It's sent by a company to a user, who chooses whether to share a presentation in response.+ More...requests for presentations and send them to subjects.
important
A company can be both an
Example: Hooli FinTech sends Richard a request for (a presentation of) a KYC verification credential from ACME Bank. When Richard shares the presentation, Hooli verifies it.
Components: A verifier verifies presentations and makes requests using the Server SDK. It displays requests using the Web SDK and sends them to subjects using the Server SDK.
To register a verifier and recieve a verifier API key, a company (already registered as an Unum ID customer) submits to us two pieces of information:
- name (human readable)
- endpoint (to receive presentations)
The name is used in the Mobile SDK and Web SDK to display content to users. We send (encrypted) presentations to the endpoint, which passes them to the Server SDK to be verified. (We provide an OpenAPI spec and reference endpoint, so creating the endpoint is very simple.)
#
DIDA DID (or decentralized identifier) identifies a participant in the Unum ID ecosystem. A participant is an
An issuer is a role a company can play to issue credentials to subjects (users). An issuer also change credential statuses, for example to revoke credentials.+ More...issuer,+ More...subject, orA verifier is a role a company can play to verify presentations shared by subjects (users). A verifier can also make requests for presentations and send them to subjects.+ More...verifier.
note
The technical details of DIDs are not relevant to deploying or using Unum ID. You can think of DIDs as identifiers in the normal sense โ unique, random strings of characters (like UUIDs).
However, if you're curious to learn more, read the emerging W3C specification.
Example: ACME Bank is identified by two DIDs, one for acting as an issuer and another for acting as a verifier. Richard, an ACME subject (user), is identified by one DID. Hooli FinTech, which acts as a verifier, is identified by one DID.
Components: The Server SDK returns DIDs for issuers and verifiers, and the Mobile SDK returns DIDs for subjects.