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 will interact with in this scenario. For our demo, we will need to create mock versions of these organizations before we begin.


  1. Go to the Trinsic Studio and log in.
  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 card to enter into the organization. 
2. Go to the **Credentials** tab and click the **Create Template** button. 
3. Using the **New Schema** tab, name the credential "College Transcript" and add these five attributes:
    - First Name
    - Last Name
    - Degree
    - Year
    - GPA
4. Click **Continue to Review** and the **Confirm**. There will be a 1-3 second delay while the template is written to the ledger.
5. Copy the credential's Schema ID for later

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 **Offer** icon that corresponds with that template.
4. Fill in all the attributes with Alice's information, then send the credential via **Create Offer Link**.
CredentialContract transcriptCredential = await faberClient.CreateCredentialAsync(new CredentialOfferParameters{
    DefinitionId = transcriptCredentialId,
    ConnectionId = faberConnectionId, // Can be null for connectionless
    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, // Can be null for connectionless
  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 can scan the QR code with the Trinsic wallet to view the details.
  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

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. Click the **Generate Invitation** button.
4. 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 acmeConnection = await acmeClient.CreateConnectionAsync(new ConnectionInvitationParameters());
let acmeConnection = await acmeClient.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. Click on the **information** icon
4. 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 Template** button. 
2. Name the verification "Job Application".
3. Click on the **+ Credential Request**.
4. Enter "Transcript Verification" as the "Requested Credential Name".
5. In the **Attribute Name** textbox, enter the attribute names exactly as they appear in the credential template that you created for Faber College.
6. In the **Advanced** 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. 
7. Click the **Create** 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 **Connections** tab in the ACME Corp organization in the Studio.
2. Locate the connection you'll use to request a verification from Alice. Click on the **blue checkmark** icon which corresponds to this connection.
3. Click the **Request Verification** button towards the bottom of the screen.
4. Select the "Job Application" from the list of templates.
5. Click **Send Request**
VerificationContract verification = await acmeClient.SendVerificationFromPolicyAsync(
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 card to enter into the organization if you're not already there. 
2. Go to the **Credentials** tab and click the **Create Template** button. 
3. Using the **New Schema** option, name the template "Employee Certificate" and add these five attributes:
    - First Name
    - Last Name
    - Salary
    - Experience
    - Start Date
4. Click **Continue to Review** then **Confirm**. 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 **card** icon.
3. Click the **Offer Credential** button.
4. Select "Employee Certificate" from the dropdown.
5. 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 😊


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.

Did this page help you?