Skip to main content

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:

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...
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.
credential).

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#

Credential#

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.

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):

  1. type of the credential
  2. identifier for the person
  3. data about the person
  4. 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:

{
"@context": ["https://www.w3.org/2018/credentials/v1"],
"credentialStatus": {
"id": "https://api.unum.id/credentialStatus/f8287c1e-0c56-460a-92af-5519f5c10cbf",
"type": "CredentialStatus"
},
// type of credential
"type": ["VerifiableCredential", "UsernameCredential"],
// a string representation of an object with with an id attribute and any number of arbitrary key value pairs.
"credentialSubject": stringify({
// identifier for the person
"id": "did:unum:5f5eb3dd-d0e0-4356-bfdd-96bc1393c705",
// data about the person
"username": "Analyst-Shoes-278"
}),
// identifier for the company
"issuer": "did:unum:7fc1753e-cdb7-428a-b6ce-eefc0e3634e5",
"id": "f8287c1e-0c56-460a-92af-5519f5c10cbf",
"issuanceDate": "2021-01-09T02:23:54.844Z",
"expirationDate": "2022-01-09T00:00:00.000Z",
// cryptographic signature, created with company's private key
"proof": {
"created": "2021-01-09T02:23:54.844Z",
"signatureValue": "AN1rKrsBLQWXcn3H6cD34FuN9w3crhpD3aogteduJZtu7NRKPYpgnfxFvJC1xMENaCZpcWpchWdpMZ5TYZmGohv8Y3kCpgUNG",
"type": "secp256r1Signature2020",
"verificationMethod": "did:unum:7fc1753e-cdb7-428a-b6ce-eefc0e3634e5",
"proofPurpose": "AssertionMethod"
}
}

Presentation#

A 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...
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.
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

A 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...
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.
request. The user's app first asks them if they want to share the requested information. Then, if the user chooses to share, the app prompts them to pass a biometric/passcode check. If the user passes that check, the app creates a presentation and sends it.

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:

{
"@context": ["https://www.w3.org/2018/credentials/v1"],
"type": ["VerifiablePresentation"],
// credentials contained in presentation, in this case just one
"verifiableCredential": [
{
"@context": ["https://www.w3.org/2018/credentials/v1"],
"credentialStatus": {
"id": "https://api.unum.id/credentialStatus/f8287c1e-0c56-460a-92af-5519f5c10cbf",
"type": "CredentialStatus"
},
"type": ["VerifiableCredential", "UsernameCredential"],
"credentialSubject": stringify({
"id": "did:unum:5f5eb3dd-d0e0-4356-bfdd-96bc1393c705",
"username": "Analyst-Shoes-278"
}),
"issuer": "did:unum:7fc1753e-cdb7-428a-b6ce-eefc0e3634e5",
"id": "f8287c1e-0c56-460a-92af-5519f5c10cbf",
"issuanceDate": "2021-01-09T02:23:54.844Z",
"expirationDate": "2022-01-09T00:00:00.000Z",
"proof": {
"created": "2021-01-09T02:23:54.844Z",
"signatureValue": "AN1rKrsBLQWXcn3H6cD34FuN9w3crhpD3aogteduJZtu7NRKPYpgnfxFvJC1xMENaCZpcWpchWdpMZ5TYZmGohv8Y3kCpgUNG",
"type": "secp256r1Signature2020",
"verificationMethod": "did:unum:7fc1753e-cdb7-428a-b6ce-eefc0e3634e5",
"proofPurpose": "AssertionMethod"
}
}
],
// request presentation is in response to
"presentationRequestUuid": "0b46168a-3f7c-4675-a8df-87930b253482",
// verifier DID that the presentation is meant for
"verifierDid": "did:unum:5f5eb3dd-d0e0-4356-bfdd-96bc1393c707",
// cryptographic signature, created with user's private key
"proof": {
"created": "2021-04-21T01:45:43.390Z",
"signatureValue": "381yXZTdpHAZ5QvX8j5cXHLGXRms2KoW2cXg3rvQEhJx6eDqAzAADu8pkxqU1CoSMeMF6QsYAvpJj7ykMkAkzPMEzBLdY7BF",
"type": "secp256r1Signature2020",
"verificationMethod": "did:unum:9d79fab6-65d7-455d-9160-780b4c152ef6#38de59ae-d475-45b1-8d6b-38764aeec96f",
"proofPurpose": "assertionMethod"
}
}

Request#

A 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...
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.
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):

  1. identifier for the company

and a list containing, for each credential:

  1. type of the credential
  2. 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...
    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.
    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

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...
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.
issuer of the credential can be the same company as the one making the request (the
A 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...
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 requests and verifies presentations using the Server SDK.
verifier)! This is the case for our Passwordless Auth product. A single company issues an authentication credential to a user, who later shares a presentation containing that credential back with the company to authenticate.

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.

{
// the base presentation object
"presentationRequest": {
"uuid": "47609f52-2cd9-4844-8cec-4fc289c7ddcd",
"createdAt": "2021-04-21T01:39:26.983Z",
"updatedAt": "2021-04-21T01:39:26.983Z",
// default is 10 minutes after creation, but this can be overriden
"expiresAt": "2021-04-21T01:49:26.983Z",
// identifier for the company
"verifier": "did:unum:f2054199-1069-4337-a588-83d099e79d44",
// credentials requested to be included in presentation, in this case only one
"credentialRequests": [
{
// type of credential
"type": "UsernameCredential",
// acceptable issuer(s) of credential, in this case only one
"issuers": [
"did:unum:7fc1753e-cdb7-428a-b6ce-eefc0e3634e5"
],
"required": true
}
],
// cryptographic signature, created with company's private key
"proof": {
"created": "2021-04-21T01:39:26.984Z",
"signatureValue": "AN1rKoiKg91BdpsLTFg6nBctDJwJEjYu6fBJheP6G5se5bRs4oWXu5TR3pdP9WZ5RgiiFWP4bKgfrBgBSmtHfxnwURKDq7das",
"type": "secp256r1Signature2020",
"verificationMethod": "did:unum:f2054199-1069-4337-a588-83d099e79d44",
"proofPurpose": "AssertionMethod"
},
"metadata": {},
"holderAppUuid": "91514d8e-b5b2-41d9-9744-3cbb2bb9a85d"
},
// enriched verifier information based on the base presentation request
"verifier": {
"name": “The Dev Shop“,
"did": "did:unum:f2054199-1069-4337-a588-83d099e79d44",
"url": "https://developer.demo.unum.id/presentation"
},
// enriched issuer information based on the base presentation request
"issuers": {
"did:unum:7fc1753e-cdb7-428a-b6ce-eefc0e3634e5": {
"name": "Acme Co Issuer",
"did": "did:unum:7fc1753e-cdb7-428a-b6ce-eefc0e3634e5"
}
},
// enriched holder app information based on the base presentation request
"holderApp": {
"name": "ACME, Inc. Test App",
"uriScheme": "unumid://",
"deeplinkButtonImg": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAb4AAABWCAYAAACw7fOyAAAABGdBTUEAALGPC…”
},
// a deeplink when opened will present the request in the holder app (or take them to the store to download if not installed), facilitating a user responding to the request in the holder app
"deeplink": "unumid://unumid/presentationRequest/47609f52-2cd9-4844-8cec-4fc289c7ddcd",
// a qr code facilitates a user responding to the request in the holder app when scanned
"qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAALQAAAC0CAYAAAA9zQYyAAAAAklEQVR4AewaftIAAAWUSURBV…”
}

Less Important Terms#

When 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.

Issuer#

An 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...
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.
credentials to
A subject is a user of a holder app. Each subject uses one or more holders.
+ More...
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.
subjects (users). An issuer can also change credential statuses, for example to revoke credentials.

important

A company can be both 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...
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.
issuer and a
A 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...
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 requests and verifies presentations using the Server SDK.
verifier! In fact, it can play the roles of many different issuers and verifiers. For example, to implement our Passwordless Auth, a single company issues an authentication credential to a user, who later shares a presentation (containing that credential), which the company verifies.

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:

  1. name (human readable)
  2. logo icon
  3. brand colors

These are used in the Mobile SDK and Web SDK to display content to users.

Holder App#

A 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...
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.
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.

Holder#

A holder is an instance of a

A holder app is an Unum ID enabled mobile app. See also: holder.
+ More...
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.
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...
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.
credentials for a
A subject is a user of a holder app. Each subject uses one or more holders.
+ More...
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.
subject (user). It also allows the subject to respond to
A 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...
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.
requests and share
A presentation is a set of one or more credentials. It's shared with (or presented to) a company by a user.
+ More...
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.
presentations.

note

The definition of a holder includes an app instance on a particular device for two reasons:

  1. A holder app stores different credentials for different users.
  2. 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.

Subject#

A subject is a user of a

A holder app is an Unum ID enabled mobile app. See also: holder.
+ More...
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.
holder app. Each subject uses one or more
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...
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.
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.

Verifier#

A 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...
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.
presentations shared by
A subject is a user of a holder app. Each subject uses one or more holders.
+ More...
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.
subjects (users). A verifier can also make
A 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...
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.
requests for presentations and send them to subjects.

important

A company can be both 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...
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.
issuer and a
A 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...
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 requests and verifies presentations using the Server SDK.
verifier! In fact, it can play the roles of many different issuers and verifiers. For example, to implement our Passwordless Auth product, a single company issues an authentication credential to a user, who later shares a presentation (containing that credential), which the company verifies.

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:

  1. name (human readable)
  2. 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.)

DID#

A 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...
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.
issuer,
A subject is a user of a holder app. Each subject uses one or more holders.
+ More...
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.
subject, or
A 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...
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 requests and verifies presentations using the Server SDK.
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.