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 a second organization called "ACME Corp."

📘

What just happened?

When you create an Organization in Trinsic, you're creating a cloud agent hosted on a dedicated tenant in the Trinsic platform capable of issuing or verifying credentials. This Organization also gets a public DID on the network it's provisioned on.

Create credentials

Alice will receive her transcript from Faber College in a digital format. In order for that to happen, Faber college has to setup a template. To learn more about how credentials work, see our documentation on credentials.

Create Faber College's Transcript Template

You can create credential templates in the Studio, through one of our SDKs, or by calling 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"
});

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.

In order to accept a digital credential, Alice will need a digital wallet. When we say WalletWallet - Software that securely stores credentials. It also stores identifiers, proofs, messages, and other information exchanged between two agents., we're referring to a software application that's sometimes called an AgentAgent - An agent is a software program that controls wallets, keys, credentials, and other information on your behalf. Trinsic develops different kinds of agents to help you achieve your goals, whether as an organization issuing credentials or a person storing credentials on your phone. Instead of using the term "agent" in our products, we use more accessible terminology like "wallet" or "organization." Your Trinsic account enables you to create as many agents as you'd like. We call institutional/enterprise agents (capable of issuing and verifying credentials) organization.. This wallet could be a web, desktop, or mobile app (Trinsic has tools to help you build all different kinds of wallets!) but today, we recommend you download the Trinsic Wallet on your phone.

Install Trinsic Wallet

Click here to download the Trinsic Wallet for iOS or Android.

Once you've downloaded the wallet, it's time for Alice to get her credential!

🚧

Selecting the right network

The wallet comes pre-configured to Sovrin MainNet, but you're using the StagingNet for this demo. Therefore, you'll need to switch to the StagingNet. Simply go to your settings and switch networks from there. See the GIF below for a walkthrough.

Faber College issues a transcript to Alice

Here's where the magic happens! Execute one of the options below or use the POST /credentials endpoint directly.

As Faber College:

1. Navigate to the **Credentials** tab in the Faber College Organization in the Trinsic Studio.
2. Locate the "College Transcript" credential template.
3. Click on the **ISSUE** button that corresponds with that template.
4. Fill in all the attributes with Alice's information, then send the credential via **Generate QR Code/Link**.
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 Add to Wallet.
  3. The credential will be issued to your wallet, and you can view it in the Wallet tab.

Alice gets a job

If you haven't already, create an Organization for ACME Corp.

Go back to the Dashboard in the Studio and click the + Organization button to add ACME Corp, if you haven't already. If you've already created ACME Corp, click on the ACME Corp organization card. Tip: you can also create organizations programmatically using the Provider API!

Alice creates a connection with ACME Corp.

A ConnectionConnection - A connection is a peer-to-peer relationship using a pairwise key exchange. It is the most secure way to offer, issue, and verify credential. The process of establishing connections is described in Aries RFC 0023: DID Exchange Protocol 1.0. is a pairwise key (and endpoint) exchange to give two parties a secure, peer-to-peer communication channel. It is an optional way to securely exchange credentials. (Note: we skipped this step for the Faber College credential!) Read more about connections here.

The first step to create a connection is to send an invitation. Connection invitations are usually transmitted through QR codes or deeplinks. In reality, ACME might embed this QR code in Alice's online job application or send her an email containing the code.

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

As ACME Corp, use Trinsic Studio to create a connection with Alice by:

1. Click on the **ACME Corp** organization card to enter into the organization. 
2. Go to the **Connections** tab and click the **+ invite connection** button. 
3. You should see a QR code appear in the panel. You can scan the QR code, send it via email to someone, or copy the URL.
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 connection invitation shows up in the wallet, tap Accept.
  4. The connection will be added to your wallet.

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 can create a job application using a Verification TemplateVerification Template - A verification template is the term (and data model) used by Trinsic to make verifying credentials simple. All verifications are sent from a template. Behind the scenes, each template comprises one or more verification policies.. A VerificationVerification - A verification is the general term used by Trinsic to describe the act of verifying or checking the legitimacy of a credential (or a proof). Our products abstract away a lot of this complexity, but the protocol we use under the hood is described in the Aries RFC 0037: Present Proof Protocol 1.0 and is summarized as follows: 1. Propose proof (optional) 2. Proof request 3. Proof presentation 4. Ack (optional) is the process to use your credentials to prove something, and is also sometimes called a ProofProof - A proof is the verified information that is shared from a credential, from one agent to another. It is the result of a verification., Proof RequestProof Request - A proof request is a message sent from a verifier to a holder outlining the information that it would like to verify. Every verification must start with a proof request that contains a unique cryptographic challenge to avoid replay attacks., or Proof PresentationProof Presentation - A proof presentation is a message sent from a holder to the verifier responding to its request for information and cryptographic challenge. Herein, the holder uses credentials in its wallet to construct a proof and sends it to the verifier. . You can read more about Verifications here.

We will assume that ACME Corp requires the following things to hire Alice:

  • First Name
  • Last Name
  • Degree
  • Year
    All from a valid college transcript. Notice, ACME in this example doesn't require the GPA Alice graduated with. Verifications can request a subset of the information in a credential.

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 ID" from the College Transcript credential template

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. Click on the **+ Policy** dropdown and select **Attribute**.
4. Enter "Transcript Verification" as the policy name.
5. In the **Select Credential Template** dropdown, select **Define Custom Attributes**.
6. In the **Select Attributes** textbox, enter the attribute names exactly as they appear in the credential template that you created for Faber College.
7. In the **Credential Restrictions** dropdown, select **Schema ID** and paste the transcript schema ID into the textbox that appears. This is so that only credentials issued from the template you created previously will pass the verification. 
**BONUS** If you'd like to experiment with zero-knowledge proofs, click on the **+ Policy** button again and select **Predicate**. See if you can set a policy to verify Alice's GPA is greater than 3.0!
6. Click the **SAVE POLICY** button and wait a few seconds for the template to be saved.
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" ]
    },
  ],
});

ACME Corp Sends Alice a Job Application

Now that ACME has set up its verification template, it can send its verification to Alice! (Tip: using the API, you can send verifications without first making a template.)

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

As ACME Corp:

1. Click on the **Verifications** tab in the ACME Corp organization in the Studio.
2. Locate the verification template you'll use to request a verification from Alice. Click on the **REQUEST** button which corresponds to this template.
3. In the list of *Send verification request via* options, select the **Connection** option.
4. Click on the connection you've made for Alice. 
5. Click **SEND REQUEST**
VerificationContract verification = await acmeClient.SendVerificationFromPolicyAsync(
    acmeConnectionId,
    transcriptVerificationId
);
let verification = await acmeClient.sendVerificationFromPolicy(acmeConnectionId, transcriptVerificationId);

Now as Alice:

  1. Your Trinsic Wallet should get a push notification for the verification request from your ACME Corp connection.
  2. From your home screen, select the verification request to respond. Once you've opened it, you can customize the information you share if you have more than one credential that can satisfy the request.
  3. 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. Let's assume she gets the job and ACME issues her a job certificate credential.

1. Click on the **ACME Corp** organization tab to enter into the organization if you're not already there. 
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"
});

Assuming they choose to hire her, Alice should now receive an Employee Certificate to prove her employment. ACME can now send the credential to Alice via the connection they already have with her.

As ACME Corp:

1. Go to the Connections tab in the Trinsic Studio.
2. Find the connection that represents Alice and click on it.
3. Click the **ISSUE CREDENTIAL** button toward the upper-right of the information screen.
4. Fill in the values and send the credential 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. Accept the credential!
  2. Get to work 😊

Conclusion

Congratulations! If you've gotten this far, you've now used Trinsic Studio (and the Credentials API behind the scenes) to issue and verify information from an individual between two organizations.

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

Updated about 9 hours 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.