Skip to main content

Quick Start Guide

Get started with an Unum ID deployment.

This guide provides an abbreviated step-by-step guide for how to get setup as an Unum ID

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/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. For full technical details, see the documentation for each component.

Dashboard#

The Unum ID Dashboard is a self-service portal where you can manage your organization's API keys and view usage statistics. To gain access:

  1. Go to the Unum ID dashboard.
  2. Scan the QR code on the login page with your mobile device. This will take you to the Unum ID Wallet, where you'll need to create an account if you don't have one already.
  3. Click the Share Data button when the Wallet prompts you. This shares your verified email with the Dashboard, so it can create an account for you.

API Keys#

Using the Dashboard, you can create and manage issuer and verifier API keys. To create an API key:

  1. On the Company page, click the Entities tab.

  2. Click the Create Issuer or Create Verifier to create an API key. The issuer API key requires a name and ID card image. The ID card image is displayed in users' wallets when you issue credentials to them. The verifier API key only requires a name.

Server SDK#

After creating an issuer or verifier API key, you should use it with the Server SDK to register the issuer or verifier entity. This registration must be done on your server, not Unum ID's, because it involves generate private keys, which only your organization should ever access. You should store these keys securely in your own persisted data store. To register an issuer or verifier:

Node.js#

  1. If using Node.js, install the SDK module using npm i @unumid/server-sdk.

Other Runtime Languages#

If using a different runtime language, you can use the SDK via HTTP. To deploy the Issuer-Verifier HTTP wrapper project:

  1. Go to the open source Issuer-Verifier Github repo.

  2. Pull the project and deploy it along side your other apps using whatever method you are most comfortable with. The project contains a Dockerfile and as well as a CircleCI CD config file for automated deployments.

Coming Soon: Publicly accessible docker image repository.

note

An example demo project that interfaces with the SDK over HTTP is the Developer Demo.

Register Issuer#

Once the Server SDK is accessible and there is a persisted data store available, you can register an issuer:

  1. Use the SDK's registerIssuer method with your respective API key.
Example registerIssuer
const response = await registerIssuer('U7nbHmEpmZuRZMTA2ItFltan64SGKoDLYn7cMnpe4w2=', 'https://api.acme.com');
  1. Securely store the private signing and encryption keys this returns, along with 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 and authorization token.

  2. Create a /userCredentialRequests endpoint, adhering to our OpenApi specification. This will allow you to receive signed

    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 credential requests and user DID information from Unum ID. Our demo applications show examples of this.

Register Verifier#

Once the Server SDK is accessible and there is a persisted data store available, you can register a verifier:

  1. Use the SDK's registerVerifier method with your respective API key.
Example registerVerifier
const response = await registerVerifier('0Hner7ibF/aHWLBvUyY4iDJ1xymbef0lzMxiS0eTGoS=', 'https://api.acme.com');
  1. Securely store the private signing and encryption keys this returns, along with 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 and authorization token.

  2. Create a /presentation endpoint, adhering to our OpenApi specification. This will allow you to receive 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.
    presentation data from our Identity Engine cloud. Our demo applications show examples of this.

Issue Credentials#

Once you have registered an issuer, stored the returned private signing and encryption keys along with the DID, and have the /userCredentialRequests endpoint, you can issue credentials to users. However, users must also have a DID and key pairs to properly receive (and eventually share) encrypted credentials. They need to have their Unum ID Wallet setup. To associate a user with a DID and prompt them to create a Wallet account, you will need to:

Associate Users with DIDs#

  1. Create and persist a unique, short-lived, one-time-use userCode to identity your user.

  2. Redirect to the Unum ID Wallet (https://wallet.unumid.co), adding the userCode and your issuer DID as URL parameters. For example:

https://wallet.unumid.co/authenticate?userCode=f85fc85b-7467-4b3f-8581-f138d8b4798g&issuer=did:unum:8b642752-aa85-491a-80d3-cd6c0ef9426n

This will prompt the user to input and verify their email and pass a biometric check. When they do so, the Unum ID Wallet will call your issuer URL on the /userCredentialRequests endpoint with the userDidAssociation attribute populated with the userCode and the newly created user DID.

  1. Store the user DID from the callback response on your user entity. The userCode attribute you created in step (1) should be deleted from the user entity at this point.

Giving Users Credentials#

  1. Use the Server SDK's issueCredentials method to issue credentials to the user. For example:
Example issueCredentials
const result: UnumDto<CredentialPb> = await issueCredentials(
'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6ImFjY2VzcyJ9.eyJ1dWlkIjoiODg1ZDQxZjktYWFiNS00YTQ1LWE2ZTUtYWY1NjM1YjlkNGI5IiwiZGlkIjpudWxsLCJlbWFpbCI6InJheSs4MDAwQHVudW1pZC5jbyIsImlhdCI6MTY1NDMwODUxNCwiZXhwIjoxNjYyOTQ4NTE0LCJhdWQiOiJsb2NhbGhvc3QiLCJpc3MiOiJmZWF0aGVycyIsInN1YiI6Ijg4NWQ0MWY5LWFhYjUtNGE0NS1hNmU1LWFmNTYzNWI5ZDRiOSIsImp0aSI6ImJjOTNjNGMyLTg5NDQtNDMxYS1iZTY5LTQ2ZjBjNDA2MjBjYSJ9.zS5ZWBxjotHpuBHUN3pDn8J8ygDFYGD3ASmJVYSt7Wc',
'did:unum:8b642752-aa85-491a-80d3-cd6c0ef9426n',
'did:unum:a0cd2e20-5f3e-423c-8382-afc722eaca9e',
[{
'type': 'SsnCredential',
'ssn': '123-45-5678
}],
'-----BEGIN PRIVATE KEY-----\nMIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgw7wRQL1EUsLk08auyjhlHV0atw0wqQGjtP3wkAIz8uChRANCAARfUK8OjrArOokLQau9W3siHlxxtt9/FGjdiiL1YM8PqHqhmgscc6oSdUUKfA/HZaf9m2yEQqQPyoFR1R16Ck/8\n-----END PRIVATE KEY-----'
);

Requesting Credentials#

Once you have registered a verifier, you can make a presentation

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. (There is no requirement to issue credentials in order to make such a request.) To make a request:

  1. Use the Server SDK's sendRequest method along with your verifier authorization token.
Example sendRequest
const response = await sendRequest(
'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoidmVyaWZpZXIiLCJ1dWlkIjoiNWJmZTZkNzktMzdkNy00ODNiLTgyZGMtYzZhYWJhMjUzOTE2IiwiZGlkIjoiZGlkOnVudW06ZDdhZDczMWUtNzBkNy00MzQxLWJlNGQtM2U3ZWIwNmRmNzZlIiwiZXhwIjoxNjQzMTc0NjM4Ljc4NCwiaWF0IjoxNjQzMTc0NjcyfQ.WLNlP-A_8DjTvmmKt6z8CfD6whh5aQHIYgT9nYjuPn0',
'did:unum:d7ad731e-70d7-4341-be4d-3e7eb06df76e',
[
{
'type':'EmailCredential',
'issuers': [
'did:unum:8b642752-aa85-491a-80d3-cd6c0ef9426n'
],
'required': true
}
],
'-----BEGIN PRIVATE KEY-----\nMIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgw7wRQL1EUsLk08auyjhlHV0atw0wqQGjtP3wkAIz8uChRANCAARfUK8OjrArOokLQau9W3siHlxxtt9/FGjdiiL1YM8PqHqhmgscc6oSdUUKfA/HZaf9m2yEQqQPyoFR1R16Ck/8\n-----END PRIVATE KEY-----',
'7a1b0e37-efda-4b92-873b-ad7a8491175d'
);
  1. Direct the user to the response's deeplink URL for them to use the Unum ID Wallet to respond to the request by sharing their data.