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

Credentials

Verifiable CredentialsVerifiable Credentials - A credential is a set of attributes about someone or something. Typically, credentials are digital versions of physical licenses, cards, documents, or certificates, but they can represent all kinds of abstract data. They are based on the W3C VC Data Model.("VCs", or "credentials") are digital documents that conform to the W3C Verifiable Credential Data Model. VCs provide a standard for digitally issuing, holding, and verifying data about a subject.

📘

Definition of Verifiable Credential

"A verifiable credential is a set of tamper-evident claims and metadata that cryptographically prove who issued it." https://www.w3.org/TR/vc-data-model/

Verifiable credentials are unique from other kinds of digital documents because they enable you to verify the following things:

  1. The original issuing entity (the source of the data)
  2. It was issued to the entity presenting it (the subject of the data)
  3. It hasn't been tampered with (the veracity of the data)
  4. Whether the issuer revoked the credential as of a particular point in time (the status of the data)

Often called the "Trust Triangle," this classic diagram helps conceptualize the verifiable credential model.

Components of a Credential

To break down the components of a credential, we'll use a digital driver's license as an example.

Issuer DID

As you can see from the diagram above, a VerifierVerifier - A verifier is an agent that is set up for verifications. Every organization created in the Trinsic platform is a verifier by default. will only accept a credential if they trust its source. For example, in the United States a TSA agent will only let you on an airplane if you present a valid driver's license (or other gov ID); they do this because they trust the DMV or other agency that issued it. In order to validate where a credential came from, verifiers use the issuer's DID.

Each new TenantTenant - A tenant is synonymous with organization. It is an agent provisioned with the capability to issue or verify credentials. For the sake of clarity, our core products (Wallet / Studio) will only refer to "organizations". is assigned an issuer DID on the network your tenant is provisioned to. The issuer DID acts as a public-facing address or public key. In the self-sovereign identity space, these DIDs are usually written to a public blockchain, but other DID registries are possible, too. Each issuer DID has an associated private key which is used to cryptographically "sign" each issued credential. In fact, each attribute inside the credential is signed in this manner, allowing the holder of the credential to share only a subset of the attributes when desired. For example, someone could share their name and age from their driver's license without sharing the driver's license number, address, and hair color. Using the issuer DID and straightforward public-private key cryptography, anyone can verify the attributes in the credential were attested to by the issuer.

In the Trinsic Studio, you can find your issuer DID toward the bottom of the Organization page:

Schema

Each credential needs a template so the data can be shared and interpreted correctly. That template is called a SchemaSchema - A schema is an outline for what a credential should look like. It defines what attributes will go in the credential. Ideally, schemas will be reused as much as possible to facilitate interoperability..

Schemas are the general structure of the credential. In our example, they tell us what information must be included on the driver's license in order for it to be valid, like Full name, Address, Eye color, etc.

In short, they are the attributes that you want to include in this credential.

Example:

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "description": "Email",
    "type": "object",
    "properties": {
        "emailAddress": {
            "type": "string",
            "format": "email"
            }
        },
    "required": ["emailAddress"],
    "additionalProperties": false
}

Schemas also need to be discoverable by the verifier of the credential. Because of the Hyperledger Indy/Aries tech stack that we use, we write the schema object to the public ledger. Other implementations leverage schema.org or other publicly discoverable sources.

Schemas are nonproprietary; any issuer can view/use the schemas written by any other issuer.

We abstract schema creation away into the same action as creation of a credential definition. Keep reading to read how to create a schema and credential definition.

Credential Definition

Just having an issuer DID and a schema written to the ledger is not enough, however. You need to put them together in order to actually issue credentials. This is where the Credential DefinitionCredential Definition - The technical artifact upon which credentials are based. It is a machine-readable semantic structure and includes cryptographic primitives required to facilitate credential issuance. It's based on an existing schema (or, a new schema can be created simultaneously with the credential definition). A new credential definition is created for every credential template an issuer creates. comes in.

A credential definition is a particular issuer's template to issue credentials from. There are two ways for an issuer to create a credential definition:

  1. Based on an existing schema: This is the ideal way to create a credential definition because the issuer can leverage an existing schema. In addition, this promotes interoperability and trust in credentials at scale (passports, transcripts, and employee ID cards should all be based on similar data models, for example).
  2. Create a new schema alongside the credential definition: This is the most common method of creating a credential definition in the early days because there is no existing directory of standard schemas.

Going back to our example, the New York DMV would create a Credential DefinitionCredential Definition - The technical artifact upon which credentials are based. It is a machine-readable semantic structure and includes cryptographic primitives required to facilitate credential issuance. It's based on an existing schema (or, a new schema can be created simultaneously with the credential definition). A new credential definition is created for every credential template an issuer creates. with their issuer DID and the schema. They're likely to use an existing schema, ideally the same one used by other states. Once they've created a credential definition, they can then go forward with issuing New York Driver's Licenses.

Remember this:

  • Credential definitions are the combination of schemas and issuer DIDs and act as a template for issuance (in fact, we call them credential templates in the Trinsic StudioTrinsic Studio - The Trinsic Studio is a web application that performs several important functions in the Trinsic platform. 1. Enables developers to access API keys 2. Facilitates secure payment details submission 3. Enables non developers to build proof of concepts and demos 4. Gives developers a GUI to interact with to view credential templates, verification policies, etc. 5. Enables teams to collaborate on a single organization (coming soon!)!
  • Credential definitions and schemas are permanent artifacts on the ledger that can't be edited.

To learn how to create schemas and credential definitions, see our API Reference docs.

Credential

In order to issue a credential, you need a credential definition (called a credential template in the Trinsic StudioTrinsic Studio - The Trinsic Studio is a web application that performs several important functions in the Trinsic platform. 1. Enables developers to access API keys 2. Facilitates secure payment details submission 3. Enables non developers to build proof of concepts and demos 4. Gives developers a GUI to interact with to view credential templates, verification policies, etc. 5. Enables teams to collaborate on a single organization (coming soon!). Once you have the credential definition, all you need to do is to populate the values and offer it to a holder.

{
    "credentialId": "string",
    "state": "Offered",
    "connectionId": "string",
    "definitionId": "string",
    "schemaId": "string",
    "values": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
    }
}

How to offer Credentials in Trinsic

Issue your first credential by following our tutorial.

Updated 2 months ago


Credentials


Suggested Edits are limited on API Reference Pages

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