Skip to main content

Server SDK

This is a lightweight TypeScript SDK that lets your company act as one or more

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.
issuers and/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.
verifiers.

Before you begin: Please read the deployment overview. You need to be registered as an Unum ID customer, and you need to register at least one issuer or verifier. (You can register zero to many of each, depending on your use case.) You'll receive issuer and verifier API keys to use with this SDK.

note

Auto generated SDK documentation can be found here. Similar documentation for object definitions can be found here. The auto generated documentation is more granular then this page, however less styled.

Overview#

The Server SDK uses the UnumDto type to facilitate handling many response body types, while providing a reliable structure to access the result body (and, importantly, the rolling JWT authToken).

UnumDto
{
"authToken": string; // The JWT which is used by the SDK to authenticate with UnumID's SaaS. This is periodically refreshed thus its value should be read and stored in every resultant function call.
"body": T; // The placeholder for the function's response type is function specific.
}

Authentication#

Every request detailed below requires a JWT bearer authToken as a first parameter (aside from registration calls which require an entity scoped ApiKey). This is used to authenticate requests to the Unum ID cloud. This auth token is updated on every subsequent function call and should be read via the authToken attribute and persisted accordingly for later requests.

Errors#

Errors returned by the Unum ID cloud will also be wrapped in the UnumDto object so that the potentially updated authToken can be retrieved. Validation errors, which are created prior to any calls to Unum ID, will be of type Error and are thrown. Because in this case a network call is never made, there's no potential new authToken to pass back. For this reason, we recommend wrapping all SDK calls in a try/catch.

Distribution#

This project is open source and publicly published on the official npm registry. For example it can be pulled with:

npm i @unumid/server-sdk

or

yarn add @unumid/server-sdk

Global Dependencies#

  • Node.js v14.0.0 or higher (preferably v14.15.0 or higher)
  • Yarn

Usage#

The following environment variables are required to be set to use the SDK properly.

  • UNUM_ENV
  • LOG_LEVEL
  • DEBUG

UNUM_ENV#

One needs to provide the SDK the with an environment variable to denote its run time environment, i.e. production. For the Typescript SDK this done via the UNUM_ENV environment variable. The three relevant values are: production, sandbox, dev. You need to use one of these exactly in order for the SDK to communicate with Unum ID's SaaS. The default value if nothing is supplied is sandbox.

LOG_LEVEL#

The default logs level is info. You can change this to debug for more information (set the environment variable LOG_LEVEL = debug). The logs default to stdout, so you can easily aggregate them from disk using the log provider of your choice.

We use standard NPM log levels. Learn more about these here.

DEBUG#

The DEBUG environment variable defaults to false. Setting to true enables logging of decrypted presentations at the debug level. Due to presentations containing potentially sensitive information it is not advised to use in a production environment. Note: the LOG_LEVEL environment variable also needs to be set to at least debug level in order to be visible.

Issuer#

You can use the Server SDK to act as 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, for example to issue credentials and change credential statuses.

Jump to:


registerIssuer#

Register 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 (corresponding to your customer UUID and issuer API key).

As a customer, you can register as many issuers as you like (or none at all), depending on your use case. Note, however, that you'll need a unique issuer API key for each one.

important

You need to store the

A DID (or decentralized identifier) identifies a participant in the Unum ID ecosystem. A participant is an issuer, subject, or verifier.
+ More...
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.
DID (did) and encryption and signing key pairs (keys) that this returns. You'll need these to issue credentials to users.

danger

The DID and public keys are nonsensitive, but you should store the private keys securely and never share them.

Parameters#

"customerUuid": string, // your customer UUID
"apiKey": string // your issuer API key

Response Body: RegisteredIssuer#

RegisteredIssuer
{
"uuid": string, // identifies issuer in Unum ID database
"customerUuid": string, // identifies customer in Unum ID database
/* To store: */
"did": string, // identifies issuer in Unum ID ecosystem
"name": string, // human-readable name for issuer. Displayed to users in mobile apps when verifiers request credentials. Comes from the name of the ApiKey used to register the Issuer.
"createdAt": string, // when issuer was registered
"updatedAt": string, // when issuer was last updated
/* To store: */
"keys": {
"signing": {
"privateKey": string, // you use this to create signatures on credentials
"publicKey": string, // subjects and verifiers use this to verify your signatures on credentials
}
"encryption": {
"privateKey": string, // could be used to decrypted data, however the encryption key pair is not currently used by issuers
"publicKey": string, // could be used for others to encrypt data, however the encryption key pair is not currently used by issuers
}
}
}

issueCredentials#

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

You need to provide:

  1. your
    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 DID (or decentralized identifier) identifies a participant in the Unum ID ecosystem. A participant is an issuer, subject, or verifier.
    + More...
    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.
    DID
  2. your issuer signing private key
  3. data array about the
    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 the
    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
  4. the target subject DID to receive the credentials

The first two are returned by registerIssuer. The third (credential types) is part of what verifiers use 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.
request credentials from users. For example, Hooli FinTech might request a credential of type KYCVerification, issued by ACME Bank. The fourth (data about the subject) can be any valid JSON.

You can optionally provide:

  1. expiration date
note

An expiration date is not the only control on whether a credential is valid. You can also change the credential's status at any time, for example to revoke it (see updateCredentialStatus).

Each issued credential contains a credential id that you should store. You'll need this, for example, if you ever want to revoke the credential. We recommend storing the entire credential, indexed on the credential id. If you only store the credential id, it'll be very difficult to later remember what the id corresponds to.

note

In the full credential objects that are returned, there are also id fields within credentialSubject and credentialStatus, but these are different. They refer to the subject

A DID (or decentralized identifier) identifies a participant in the Unum ID ecosystem. A participant is an issuer, subject, or verifier.
+ More...
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.
DID and credential status identifiers, respectively, as defined in the emerging W3C Verifiable Credential specification.

important

The private key never leaves your server. The Server SDK only needs it to perform cryptographic functions on your behalf.

Parameters#

"authToken": string, // your auth token
"issuer": string, // your issuer DID
"subject": string, // the target subject DID to receive the credentials
"credentialDataList": [{
"type": string, // The credential type
[key: string]: any, // data about subject (any valid JSON)
}],
"signingPrivateKey": string // your issuer signing private key
"expirationDate"?: string, // (optional) when credential will no longer be valid (ISO 8601 date/time)

Response Body: Credential Array#

Credential
[{
"@context": ["https://www.w3.org/2018/credentials/v1"], // for conformance with W3C Verifiable Credential spec
"credentialStatus": {
"id": string, // a url for credential's status
"type": "CredentialStatus"
},
// a string representation of an object with with an id attribute and any number of arbitrary key value pairs.
"credentialSubject": stringify({
"id": string, // subject DID
[key: string]: any, // // credential data about subject
}),
"issuer": string, // issuer DID
"type": string[], // credential type(s), always begins with "VerifiableCredential" per W3C standard
/* To store: */
"id": string, // identifies credential (version 4 UUID)
"issuanceDate": string, // when credential was issued (ISO 8601 date/time)
"expirationDate": string, // when credential will no longer be valid (ISO 8601 date-time)
"proof": Proof // cryptographic proof created by signing credential with your issuer signing private key. Can be used to verify credential.
}]

updateCredentialStatus#

Update a

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's status (i.e. make it invalid).

You need to provide the credential id (which is issueCredentials returns per

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) and a CredentialStatusOptions status. Currently there are only two valid statuses: "valid" and "revoked".

note

As noted in issueCredentials, we recommend storing the each entire credential, indexed on their credential id. If you only store the credential id, it'll be very difficult to later remember what the id corresponds to.

CredentialStatusOptions
export type CredentialStatusOptions = 'valid' | 'revoked';

Parameters#

{
"authToken": string, // your auth token
"credentialId": string, // id of the credential
"status": CredentialStatusOptions // status to update the credential to (defaults to 'revoked')
}

Response Body: Empty#

If unsuccessful, an exception will be thrown.

{}

revokeAllCredentials#

Revoke all

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 (i.e. make all invalid).

You need to provide your issuer's did and signingPrivateKey also the target subjectDid. Only credentials issued by the associated issuer are revoked from the subject. The signing private key is necessary for the request signature to be created within the SDK. The signature is necessary to be verified by the SaaS prior to revoking all the credentials.

important

The signing private key never leaves your server. The Server SDK only needs it to perform cryptographic functions on your behalf.

Parameters#

{
"issuerDid": string // did of the issuer of credential you would like to revoke
"signingPrivateKey": string // issuer's signing private key
"subjectDid": string // did of target subject whom to revoke all the credentials issued by the issuer
}

Response Body: Empty#

If unsuccessful, an exception will be thrown.

{}

verifySubjectCredentialRequests#

Verify 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's request for
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.

You need to be able to receive these credential requests from Unum ID and pass them to this function. To do this, you need to create a /userCredentialRequests endpoint that conforms to our OpenAPI specification.

Each request is cryptographically signed by the

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's private key. This function verifies the signatures are valid. Furthermore, it validates that all requests are from the same subject and that requested Issuer requirements are met. After which, your application code will need to evaluate wether it can issue the requested credentials. An example implementation can be found here.

The main use case of this to allow bootstrapping users that just installed the Unum ID Wallet with credentials necessary to use across the network, i.e for instant sign ups with a partner.

note

Despite this having "verify" in its name, this function serves Issuers in determining whether a subject's request for credentials is valid. It is up to your application logic to determine whether you have the data relating to the the subject to issue the requested credentials.

CredentialRequest
{
type: string; // the string matching the desire credential type
issuers: string[]; //list of acceptable issuer DIDs that have issued the credential
required: boolean; // to denote wether this particular credential is required. Defaults behavior resolves this to true.
}
SubjectCredentialRequests
{
credentialRequests: CredentialRequests[]; // the string matching the desire credential type
proof: Proof; // proof signed by the subject
}

Parameters#

{
"authToken": string, // your auth token
"issuerDid": string, // the did of your issuer
"subjectDid": string // the did of the subject
"subjectCredentialRequests: SubjectCredentialRequests // object containing list of CredentialRequests with a Proof signed by the Subject.
}
important

All parameters aside from the authToken ought to be provided verbatim via the specified OpenApi /userCredentialRequests endpoint.

Response Body: VerifiedStatus#

VerifiedStatus
{
isVerified: boolean; // returns true if all requests are verified and validation requirements are met
message?: string; // (optional) only populated iff isVerified is false
}

Verifier#

You can use the Server SDK to act as an

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, for example to 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 and 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.

Jump to:


registerVerifier#

Register 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 (corresponding to your customer UUID and verifier API key).

As a customer, you can register as many verifiers as you like (or none at all), depending on your use case. Note, however, that you'll need a unique verifier API key for each one.

The VersionInfo denotes how encrypted

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 from Unum ID's SaaS, which originate from the Mobile SDK, should be routed to your application in order for the corresponding Server SDK version to preform verifications.

important

You need to store the

A DID (or decentralized identifier) identifies a participant in the Unum ID ecosystem. A participant is an issuer, subject, or verifier.
+ More...
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.
DID (did) and encryption and signing key pairs (keys) that this returns. You'll need these to make requests and verify presentations.

danger

The DID and public keys are nonsensitive, but you should store the private keys securely and never share them.

Parameters#

"customerUuid": string, // your customer UUID
"url": string, // the url of which UnumID's SaaS will interface with
"apiKey": string // your verifier API key
"versionInfoList": VersionInfo[] // the versioning information of your application corresponding to various Unum ID Server SDK versions.

Response Body: RegisteredVerifier#

RegisteredVerifier
{
"uuid": string, // identifies verifier in Unum ID database
"customerUuid": string, // identifies customer in Unum ID database
/* To store: */
"did": string, // identifiers verifier in Unum ID ecosystem
"name": string, // human-readable name for verifier. Displayed to users in mobile apps when you make requests. Comes from the name of the ApiKey used to register the Verifier.
"createdAt": string, // when verifier was registered (ISO 8601 date/time)
"updatedAt": string, // when verifier was last updated (ISO 8601 date/time)
/* To store: */
"keys": {
"signing": {
"privateKey": string, // you use this to create signatures on requests
"publicKey": string, // subjects use this to verify your signatures on requests
}, "encryption": {
"privateKey": string, // you use this to decrypt presentations you receive from subjects
"publicKey": string, // subjects use this to encrypt presentations they send to you
}
}
}

sendRequest#

Create 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 to be displayed or sent to 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.

You need to provide:

  1. your verifier
    A DID (or decentralized identifier) identifies a participant in the Unum ID ecosystem. A participant is an issuer, subject, or verifier.
    + More...
    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.
    DID
  2. your verifier signing private key
  3. 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 UUID
  4. credential request(s)

The first two are returned by registerVerifier. The third (holder app UUID) identifies the mobile app users will 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 from. For example, Hooli FinTech might use the UUID for ACME Bank's mobile app, so the user is prompted to share a presentation from that app.

The fourth (credential requests) encodes which

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 you're asking the user to include in a presentation. It's a list of one or more CredentialRequest objects (defined in the Unum ID generic types project):

CredentialRequest
{
type: string; // credential type. This must match type of previously issued credential.
issuers: string[]; // list of DIDs for acceptable issuers. If multiple, any one is acceptable.
required?: boolean; // if credential is required (default is true)
}

If you list multiple

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.
issuers, the user can include a credential issued by any one of those listed.

You can optionally provide:

  1. expiration date
  2. metadata
important

The private key never leaves your server. The Server SDK only needs it to perform cryptographic functions on your behalf.

Parameters#

"authToken": string, // your auth token
"verifier": string, // your verifier DID
"credentialRequests": CredentialRequest[], // a list of one or more CredentialRequest objects. Encodes which credentials should be included in presentation that responds to PresentationRequest.
"signingPrivateKey": string, // your verifier signing private key
"holderAppUuid": string, // identifies mobile app subjects will share presentations from
"expiresAt"?: string, // (optional) when PresentationRequest will no longer be valid (ISO 8601 date/time). Default is 10 minutes after creation.
"metadata"?: object // (optional) any additional data to include in PresentationRequest

Response Body: PresentationRequestPostDto#

PresentationRequestPostDto
{
"presentationRequest": {
"uuid": string, // identifies PresentationRequest in Unum ID database
"createdAt": string, // when PresentationRequest was created (ISO 8601 date/time)
"updatedAt": string, // when PresentationRequest was last updated (ISO 8601 date/time). Should always be same as createdAt.
"expiresAt": string, // when PresentationRequest will no longer be valid (ISO 8601 date/time)
"verifier": string, // your verifier DID
"credentialRequests": CredentialRequest[], // a list of one or more CredentialRequest objects. Encodes which credentials should be included in presentation that responds to PresentationRequest.
"proof": Proof, // acryptographic proof created by signing PresentationRequest with your verifier signing private key. Can be used to verify PresentationRequest.
"metadata": object // any additional data to include in PresentationRequest
},
"verifier": {
"name": string, // human readable name for verifier. Displayed to users in mobile apps.
"did": string, // your verifier DID
"url": string // endpoint you use to receive presentations
},
"issuers": {
"IssuerDid:string": { // map keyed on issuer DID(s) that issued requested credential(s)
"name": string, // human readable name for issuer
"did": string // issuer DID
}
},
/* You send this to a user with the Web SDK: */
"deeplink": string, // deep link (URL) that can be used to trigger intended mobile app to load PresentationRequest
/* You display this to a user with the Web SDK */
"qrCode": string // QR code representation of deep link (encoded as data URL)
}

verifyPresentation#

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.
presentation 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.
subject.

You need to be able to receive presentations from users and pass them to this function. To do this, you need to create a /presentation endpoint that conforms to our OpenAPI specification. The Unum ID cloud sends encrypted presentations to this endpoint, which should pass those presentations to the verifyPresentation function to be decrypted and verified.

You need to provide:

  1. your verifier
    A DID (or decentralized identifier) identifies a participant in the Unum ID ecosystem. A participant is an issuer, subject, or verifier.
    + More...
    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.
    DID
  2. your verifier encryption private key
  3. encrypted presentation (received at /presentation endpoint)
  4. (optional, but recommended) presentation request (received at /presentation endpoint)

The fist two are returned by registerVerifier.

important

Unum ID never has access to sensitive data contained in presentations. The Mobile SDK encrypts each presentation (with your verifier encryption public key) before sending it to us. We have no ability to decrypt the data โ€” only you do.

note

presentationRequest is optional in order for the server sdk can handle verifying presentations that may not have a corresponding request. However, if presentationRequest is supplied from UnumID's SaaS via the /presentation endpoint, it is strongly recommended that it is provided as it performs additional validation checks on your behalf.

Parameters#

"authToken": string, // your auth token
"encryptedPresentation": EncryptedData, // encrypted presentation
"verifierDid": string, // your verifier DID
"encryptionPrivateKey": string // your verifier encryption private key
"presentationRequest"?: PresentationRequestDto // (optional) presentation request dto object to verify presentation credentials meet request requirements. This is an optional param to support the future use case of handling verifying presentations that are not in response to PresentationRequest

Response Body: DecryptedPresentation#

DecryptedPresentation
{
"isVerified": boolean; // whether the presentation is valid
"type": 'VerifiablePresentation' | 'DeclinedPresentation' // type of presentation. DeclinedPresentation means user declined request and the submitted presentation's VerifiableCredential attribute was undefined or an empty array.
"presentation": Presentation, // decrypted Presentation object
"message"?: string; // (optional) included if isVerified is false. Explains why verification failed.
}

You can decide what to do with the result of the verification. We recommend that you require that isVerified must be true, but depending on your use case you may want to handle this case differently.


sendSms#

This is a utility function you won't usually need. For most use cases, the Web SDK or a separate service of your choice will handle sending SMS messages. But you can use this function if helpful.

Send an SMS containing a deep link to 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.

Messages you send will (necessarily) be delivered from an Unum ID associated phone number, but this association won't be visible to the user. You can of course use your own SMS sending service if you prefer.

To request 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 from a user, you need to:

  1. create the
    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 object using sendRequest, which includes a deep link that references the request
  2. send or display the deep link to the user

SMS is one way to send the deep link. The SMS message will be in the format:

Verification Request: [verifier_name]. Click here to complete: [deep_link]

note

The verifier is corresponding to the presentation request from which the deeplink references. Because you are the acting verifier, the name will be what ever you provided during verifier registration.

Parameters#

{
"authToken": string, // your auth token
"to": string, // phone number to send SMS to
"deeplink": string // the deeplink corresponding to the presentation request you would like served to the user
}

Response Body: Empty#

If unsuccessful, an exception will be thrown.

{}

sendEmail#

This is a utility function you won't usually need. For most use cases, the Web SDK or a separate service of your choice will handle sending emails. But you can use this function if helpful.

Send an email containing a deep link to 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.

Emails you send will be delivered from no-reply@unumid.co. You can of course use your own email sending service if you prefer.

To request 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 from a user, you need to:

  1. create the
    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 object using sendRequest, which includes a deep link that references the request
  2. send or display the deep link to the user

Email is one way to send the deep link. The email will be in the format:

  • subject: Verification Request: [verifier_name]
  • body: Click here to complete: [deep_link]
note

The verifier is corresponding to the presentation request from which the deeplink references. Because you are the acting verifier, the name will be what ever you provided during verifier registration.

Parameters#

{
"authToken": string, // your auth token
"to": string, // email address to send email to
"deeplink": string // the deeplink corresponding to the presentation request you would like served to the user
}

Response Body: Empty#

If unsuccessful, an exception will be thrown.

{}

checkCredentialStatuses#

Used to check the status of individual credentials.

The status attribute of the response's CredentialStatusInfo is of type CredentialStatusOptions. Currently the only valid status are: verified and revoked.

export type CredentialStatusOptions = 'valid' | 'revoked';
export type CredentialStatusInfo {
"createdAt": Date; // the time the credential was recorded as created in the UnumID SaaS db
"updatedAt": Date; // the time the credential was recorded as updated in the UnumID SaaS db
"credentialId": string; // the did (aka id) of the credential this status is in regard to
"status": CredentialStatusOptions; // a string literal type that currently only consists of 'valid' and 'revoked'
}

Parameters#

{
"credentialIds": string[], // the array of ids of the credentials in question
}

Response Body: CredentialIdToStatusMap.#

CredentialIdToStatusMap
{
[credentialId: string]: CredentialStatusInfo;
}