Trinsic

The Trinsic Docs

Welcome to the Trinsic Docs. You'll find comprehensive guides and documentation to help you start working with Trinsic as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    API Reference

Tutorial

Get started using the Credentials API in 15 minutes

Meet Alice

This document will walk through a scenario where Alice will receive a college diploma and prove to her employer she graduated college to get a job. There are instructions in text, video, and working code samples.

Create Organizations

There are a couple of different entities that Alice with interact with in this scenario. For our demo, we will need to create mock versions of these organizations before we begin.

Steps:

  1. Go to the Trinsic Studio and login.
  2. Click on the + Organization, and create an organization called "Faber College" on the Sovrin Staging Network.
  3. Repeat Step 2 for ACME Corp.

Write an organization's public DID to the Sovrin Ledger

During this process, a couple of important interactions happened.

First, a secure wallet was created in the Trinsic ID Agency for each of these organizations. Next, a public decentralized identifier was created for each organization and was written to the Sovrin Staging ledger. Finally, endpoints were set up so that any individual can connect with that organizations when the Public DID is resolved on the ledger. There is more information about this process in the open source documentation of Hyperledger Aries.

Create credentials

Alice will receive her transcript from Faber College in a digital format. But first we need to create the digital credentials that will be used to represent these documents.

Create Faber College's Transcript

At this point, there are multiple ways to accomplish this. Either use Trinsic Studio (no coding required), use one of our SDKs, our call our API directly.

Execute one of the options below, or use the POST /definitions/credentials endpoint directly.

1. Click on the **Faber College** organization tab to enter into the organization. 
2. Go to the **Credentials** tab and click the **+ New Credential Template** button. 
3. Using the **Create a Credential Template** tab, name the credential "College Transcript" and add these five attributes:
    - First Name
    - Last Name
    - Degree
    - Year
    - GPA
4. Click **Create Template**. There will be a 1-3 second delay while the template is written to the ledger.

Congratulations! You now have a credential template written to the ledger.
CredentialDefinitionContract transcriptCredential = await faberClient.CreateCredentialDefinitionAsync(new CredentialDefinitionFromSchemaParameters {
    Name = "College Transcript",
    Version = "1.0",
    Attributes = {"First Name", "Last Name", "Degree", "GPA", "Year"},
    SupportRevocation = false,
    Tag = "default"
});
let transcriptCredential = await faberClient.createCredentialDefinition({
  name: "College Transcript",
  version: "1.0",
  attributes: ["First Name", "Last Name", "Degree", "GPA", "Year"],
  supportRevocation: false,
  tag: "default"
});

Create ACME Corp's employee credential

Execute one of the options below, or use the POST /definitions/credentials endpoint directly.

1. Click on the **ACME Corp** organization tab to enter into the organization. 
2. Go to the **Credentials** tab and click the **+ New Credential Template** button. 
3. Using the **Create a Credential Template** tab, name the credential "Employee Certificate" and add these five attributes:
    - First Name
    - Last Name
    - Salary
    - Experience
    - Start Date
4. Click **Create Template**. There will be a 1-3 second delay while the template is written to the ledger.
CredentialDefinitionContract employeeCredential = await acmeClient.CreateCredentialDefinitionAsync(new CredentialDefinitionFromSchemaParameters {
    Name = "Employee Certificate",
    Version = "1.0",
    Attributes = {"First Name", "Last Name", "Salary", "Experience", "Start Date"},
    SupportRevocation = false,
    Tag = "default"
});
let employeeCredential = await acmeClient.createCredentialDefinition({
  name: "Employee Certificate",
  version: "1.0",
  attributes: ["First Name", "Last Name", "Salary", "Experience", "Start Date"],
  supportRevocation: false,
  tag: "default"
});

Alice gets a transcript

As a graduate of Faber College, Alice receives an alumni newsletter where she learns that her alma mater is offering digital transcripts. She logs in to the college alumni website and requests her transcript by clicking the Get Transcript button.

Alice can use her mobile wallet to receive her digital transcript. This mobile wallet will become a building block for Alice's self-sovereign identity. It is a new form of digital identification. One that is portable and belongs to Alice, that nobody can use or correlate without her permission.

Using a self-sovereign identity will require a tool called a digital wallet. It's a simple desktop or mobile application that facilitates the exchange of credentials with third parties. When Alice clicks Get Transcript, Faber College will send a connection request to Alice's wallet. Once she accepts the connection request, this connection request will enable Alice to make a secure channel of communication with another party — Faber College.

In our case, Alice will install a mobile app as her wallet. Whenever she needs to receive a credential, Alice will launch the app and scan a QR code.

Install Trinsic Wallet

As an individual using self-sovereign identity, the first step is to download a digital identity wallet. This is sort of like an Apple Wallet, but it is for all the other credentials that you carry around with you.

Our identity wallet can be downloaded for both iOS and Android.

Once you have downloaded the wallet and walked through the onboarding screens, it's time to connect with Faber College to receive your credential.

Alice creates a connection with Faber College

This can be done in many ways. The most common way currently is to scan a QR code. Faber College would post this QR code on the student's online account, or send the student an email containing the code.

Execute one of the options below, or use the POST /connections endpoint directly.

As a Faber College employee, use Trinsic Studio to create a connection with Alice by:

1. Click on the **Faber College** organization tab to enter into the organization. 
2. Go to the **Connections** tab and click the **+** button. 
3. In the **Create Invitation** tab, click the **Create Invitation** button.
ConnectionContract faberConnection = await faberClient.CreateConnectionAsync(new ConnectionInvitationParameters());
let faberConnection = await faberClient.createConnection({});

Now, as Alice:

  1. Open your mobile wallet app and tap on Scan Code.
  2. Scan the QR code that is displayed in Trinsic Studio.
  3. When the invitation shows up in the wallet, tap Accept.
  4. The connection will be added to your wallet.

Faber College issues a transcript to Alice

Execute one of the options below, or use the POST /credentials endpoint directly.

As a Faber College employee:

1. If a new connection does not show up in the Connections list, refresh the page. 
2. Click on the new connection that shows up. It should be named the name of the device.
3. Click on the **+ CREDENTIAL** and select the **College Transcript** credential from the drop down. 
4. Fill in all the attributes with Alice's information, then click **Issue Credential**.
CredentialContract transcriptCredential = await faberClient.CreateCredentialAsync(new CredentialOfferParameters{
    DefinitionId = transcriptCredentialId,
    ConnectionId = faberConnectionId,
    AutomaticIssuance = true,
    CredentialValues = new Dictionary<string,string> {
        {"First Name", "Alice"},
        {"Last Name", "Smith"},
        {"Major", "Computer Science"},
        {"GPA", "4.0"},
        {"Year of Graduation", "2020"}
    },
});
let transcriptCredential = await faberClient.createCredential({
  definitionId: transcriptCredentialId,
  connectionId: faberConnectionId,
  automaticIssuance: true,
  credentialValues: {
    "First Name": "Alice",
    "Last Name": "Smith",
    "Degree": "Computer Science",
    "GPA": "4.0",
    "Year": "2020"
  }
});

Now, as Alice:

  1. Once the credential has been offered, you will see an Action appear in your wallet.
  2. Open the credential offer and inspect the attributes. If everything looks correct on your end, click Accept.
  3. The credential will be issued to your wallet, and you can view it in the Wallet tab.

Alice gets a job

Create ACME Corp job application

Now that Alice has her first credential, she can begin to use it to prove things about herself. In this case, she wants to get a job and can use her digital college transcript to do so.

ACME Corp is requesting that Alice fill out a job application.

To create the job application, we will use something called a Verification Template. To prove anything with the credentials you have received, you will need to use a verification. These can be created with Trinsic Studio or through the API.

The job application requires:

  • First Name
  • Last Name
  • Degree
  • GPA
  • Year

All from a valid college transcript.

Execute one of the options below, or use the POST /verifications/policy endpoint directly.

First, get the Schema ID for the transcript:

1. Click on the Dashboard and go to the Faber College organization. 
2. Click on the **Credentials** tab.
3. Copy the "Schema" from the College Transcript credential

Now create the Job Application template:

1. Click into Dashboard and go to the ACME Corp organization.
2. Click on the **Verifications** tab and click the **+ Create Verification Template** button. 
2. Name the verification "Job Application".
3. For each attribute (First Name, Last Name, Degree, GPA, Year), complete the following steps:
    - Click on the **+ Policy** dropdown and select **Attribute**.
    - Enter the attribute name as the policy name.
    - In the **Select Credential Template** dropdown, select **Define Custom Attributes**.
    - In the **Select Attributes** textbox, enter the attribute name exactly as entered into the credential definiton and press Enter.
    - In the **Credential Restrictions** dropdown, select **Schema ID** and paste the transcript schema ID into the textbox that appears. This limits the types of credentials that can be used to fulfill the verification.
4. Click the **SAVE POLICY** button and wait a few seconds while the verification is written to the ledger.
VerificationPolicyContract applicationVerificationPolicy = await acmeClient.CreateVerificationPolicyAsync(new VerificationPolicyParameters {
    Name = "Proof of Transcript",
    Version = "1.0",
    Attributes = new List<VerificationPolicyAttributeContract> {
        { new VerificationPolicyAttributeContract { 
            PolicyName = "First Name", 
            AttributeNames = new List<string>{"First Name"}
        }},
        { new VerificationPolicyAttributeContract { 
            PolicyName = "Last Name", 
            AttributeNames = new List<string>{"Last Name"}
        }},
        { new VerificationPolicyAttributeContract { 
            PolicyName = "Degree", 
            AttributeNames = new List<string>{"Degree"}
        }},
        { new VerificationPolicyAttributeContract { 
            PolicyName = "GPA", 
            AttributeNames = new List<string>{"GPA"}
        }},
        { new VerificationPolicyAttributeContract { 
            PolicyName = "Year", 
            AttributeNames = new List<string>{"Year"}
        }}
    },
});
let applicationVerificationPolicy = await acmeClient.createVerificationPolicy({
  name: "Proof of Transcript",
  version: "1.0",
  attributes: [
    {
      policyName: "First Name",
      attributeNames: [ "First Name" ]
    },
    {
      policyName: "Last Name",
      attributeNames: [ "Last Name" ]
    },
    {
      policyName: "Degree",
      attributeNames: [ "Degree" ]
    },
    {
      policyName: "GPA",
      attributeNames: [ "GPA" ]
    },
    {
      policyName: "Year",
      attributeNames: [ "Year" ]
    },
  ],
});

Alice connects with ACME Corp

Now it's time to become Alice again and send in a job application for ACME Corp.

First, create a connection with ACME corporation. Do this by using the same method used earlier but with the ACME Corporation organization.

ACME Corp Sends Alice a Job Application

Now that Alice has connected with ACME Corp, send a job application to Alice.

Execute one of the options below, or use the PUT /verifications/policy/policyId/connections/connectionId endpoint directly.

As ACME Corp:

1. Click on the **Connections** tab and select on the new connection that has appeared.
2. Click on the **+ VERIFICATION** button to open the **Request Verification** slider. 
3. In the **Select a Template** dropdown, select the **Job Application**.
4. Click on the **SEND REQUEST** button to send the verification request to Alice.
VerificationContract verification = await acmeClient.SendVerificationFromPolicyAsync(
    acmeConnectionId,
    transcriptVerificationId
);
let verification = await acmeClient.sendVerificationFromPolicy(acmeConnectionId, transcriptVerificationId);

Now as Alice:

  1. On Trinsic Wallet, you will receive a job application and be asked to fill in your information from your college transcript.
  2. If the information looks correct, press Accept.

ACME Corp issues Alice a job certificate

Once ACME Corp has verified that Alice received a college transcript, they can choose whether or not to hire her.

Assumming they choose to hire her, Alice should now receive an Employee Certificate to prove her employment.

Execute one of the options below, or use the POST /credentials endpoint directly.

As ACME Corp:

1. Click on the **Connections** tab and select on the new connection that has appeared.
2. Fill in the attribute information for the credential.
3. Click on the **ISSUE CREDENTIAL** button to send the verification request to Alice.
CredentialContract employeeCertificate = await acmeClient.CreateCredentialAsync(new CredentialOfferParameters {
    DefinitionId = employeeCredentialId,
    ConnectionId = acmeConnectionId,
    AutomaticIssuance = true,
    CredentialValues = new Dictionary<string,string> {
        {"Name", "Alice"},
        {"Salary", "100,000"},
        {"Experience", "4 years"},
        {"Start Date", "2020"}
    },
});
let employeeCertificate = await acmeClient.createCredential({
  definitionId: employeeCredentialId,
  connectionId: acmeConnectionId,
  automaticIssuance: true,
  credentialValues: {
    "First Name": "Alice",
    "Last Name": "Smith",
    "Salary": "100,000",
    "Experience": "4 years",
    "Start Date": "2020"
  }
});

As Alice:

  1. Once the Job Certificate offer is sent to the wallet, review the information and choose whether to accept or decline it.

Conclusion

Congratulations! If you've gotten this far, you've now used Trinsic Studio and the Credentials API to issue and verify information from an individual.

You can learn more about how to use the Trinsic products by checking out our conceptual guides or our API Reference documents.

Updated 20 days ago


Tutorial


Get started using the Credentials API in 15 minutes

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.