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

Verifications

Verifications are the mechanism through which data is requested from 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., usually held in a digital wallet.

At a high level, verifications follow a specific pattern:

  1. The verifier must first understand their risk policy. What will they accept? How will they know whether to trust the verification? These policies are known as "Verification Policies".
  2. The verifier requests some information from the credential holder. This request is known within Trinsic as a "verification request" and is called a "proof request" or "presentation request" in other circles.
  3. The holder will then choose whether/how to satisfy the request and send a response back to the verifier. The response is known within Trinsic for simplicity's sake as a "verification" but is also more accurately called a "proof presentation" or simply a "proof".
  4. Once the verifier receives the verification from the holder, they will check the digital signatures, content, and revocation status against the ledger to ensure validity.
  5. If it all checks out, the verifier will see isValid = true and the verification passes!

How verifications work

Verifier

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 verify credentials in the context of some workflow or policy. For example, a bouncer at a bar might accept your driver's license as a proof-of-age but not a student ID. A long-term care facility might require a negative COVID-19 test in the last 72 hours from a reputable lab to admit visitors into the facility. Therefore, part of getting set up as a verifier is understanding your policies for risk and assurance. Once you do, you'll want to set up 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..

Verification Templates

Verification templates are just that; reusable templates for verifications. They are composed of one or more policies. They are stored with the verifier (not a ledger or other public source). They can be easily deleted and created. They're best for verifications where

  1. You are doing the same verification frequently
  2. You need to check for revocation as of a certain time in the past (but not in real-time, see "Revoking Credentials" guide for more information on revocation)
  3. Your policies are known in advance

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!) allows you to create verification templates. The Credential APICredential API - A Trinsic product that amounts to the easiest way to exchange credentials. It is authenticated to using the access token from a specific organization. It has three primary functions: 1. Credential exchange: issuance and verification 2. Secure communication: connections and messaging 3. Admin functions: credential templates, verification policies, etc. allows you to build more flexible workflows without templates.

Verification Policies

Policies declare which data attributes a verifier will request from a holder, and any conditions that those data must meet. There are two types of policies a verifier can create.

1. Attribute Policies

Attribute policies allow you to request data simply based on the attribute name, such as "Name" or "Age." Attributes must be entered exactly as they are used in the corresponding schema. If I request an "AGE" attribute, and all you have are credentials with "Age" attributes, the verification won't be able to be completed.

2. Predicate Policies

Predicate policies leverage zero-knowledge proofs to verify that data meets a certain condition. For example, if a liquor store wanted to know if you were of age, it would create a predicate policy to check whether "Age" is greater than the legal threshold. The liquor store will only receive a "true" or "false" value.

Predicate proofs have four possible types: >=, >, <=, and <. The value name must match the attribute name exactly, both in spelling and in capitalization in order to be recognized. Because the operations are arithmetic, only numbers can be used with predicate policies.

Credential Restrictions

Credential restrictions allow the verifier to ensure they can trust the verification they get back. For example, a liquor store may choose to restrict their verifications to only allow government-issued documents. To do that, it would restrict by issuerDid but they could also restrict in other ways, see below.

  • schemaId: Anyone who creates a credential with a certain schema ID can issue it to an individual. The schema ID only provides trust that the data is in the correct format.
  • credentialDefinitionId: Because a Credential Definition is signed by an issuer, the Credential Definition defines both the format of the data and also who sent it to the wallet. This is the most commonly used restriction when contructing definitions. The Credential Definition would be an ID that is written to the Sovrin Ledger, and will prove that the credential an agent sends to you is both issued by the organization and is in the format that you need.
  • issuerDid: For situations where you only care about where the credential is from and not what format the data is in, you may also use only the issuer's DID. This is also resolvable on the Sovrin Network and will prove that the data you have received was sent from a trusted source. It will not provide any information around the format of the data that you're receiving.

As the ecosystem grows, the ability to discover trusted issuer DIDs, schema IDs, or credential IDs will get easier. For now, a useful tool is indyscan.io, which allows you to browse the Sovrin Networks for these artifacts.

Verification Requests

The first step of a verification process is for a request to be sent by the verifier to a credential holder. The request is generated from a verification template. The request step is very important because it contains a cryptographic challenge that the holder must respond to. In so doing, the verifier can be sure that the holder is responding to this specific verification request and isn't a fraudster performing a Replay Attack.

The Holder's Response

The credential holder can decide what to do with the request they get. They can either

  1. Reject the request, or
  2. Choose from their wallet which credentials they'd like to use to satisfy the request

When the holder responds to the verifier's request, they generate a nonce that satisfies the cryptographic challenge the verifier originally sent.

Doing the Verification

When the verification record is returned to the verifier, it needs to be verified against the ledger to ensure validity (I know, terminology is a bit of a challenge here). Inside the verification record are some metadata, not just the attributes themselves. This metadata includes the digital signatures of the issuer(s) of the credential(s) used, revocation details, verification policy details, etc. which are checked against the relevant sources. If the verification passes, the API will return an isValid field of true (and conversely, a false for failures).

Connectionless Verifications

One useful tool inside of the verifications suite is the ability to create connectionless verifications (see Connectionless Exchanges for more information). Essentially, you can create a verification request without the connectionId parameter. The API will return a verificationUrl that can be shared in a link or encoded as a QR Code.

These types of verifications are most useful when you don't need to have an enduring relationship with the credential holder, or when you might need several people to conduct the same verification. Examples might include one-time train tickets or COVID-19 test results.

Check out our Verifier Reference App for an example of this.

How to use in Trinsic APIs

In the Credentials API, you can perform the following functions with Verifications:

Updated 26 days ago


Verifications


Suggested Edits are limited on API Reference Pages

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