Credentials

Introduction

Credentials are one of the key concepts of self-sovereign identity. We follow the Hyperledger Aries Issue Credential Protocol 1.0 as defined by the linked RFC.

In our API, this protocol is represented using the Credentials Endpoints.

A credential is given as type CredentialContract, as shown below:

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

Create Schemas

Schemas represent the attribute structure of a Credential Definition. Schemas can either be created while creating a custom credential definition or using the API POST /definition/schemas.

const schema = await client.createSchema({
schemaParameters: {
name: "Employee Badge",
version: "1.0",
attrNames: [
"Name",
"Role",
"Email"
]
}
});

Create Credential Definitions

Credential Definitions are templates for credentials that can be issed to users. There are two ways to create definitions. Either use the an existing schema or create a custom definition. Creating custom schemas and using existing schemas can be accomplished both through the API and the Trinsic Studio.

Custom

var credentialDefinition = await client.createCredentialDefinition({
credentialDefinitionFromSchemaParameters: {
name: "Hooli Employee Badge",
version: "1.0",
attrNames: ["Name", "Role", "Email"],
supportRevocation: false,
tag: "unique identifier"
}
});

From Schema

var credentialDefinition = await client.createCredentialDefinition(schemaId, {
credentialDefinitionFromSchemaParameters: {
supportRevocation: true,
tag: "unique identifier"
}
});

Steps to issue a credential

There are 3 steps in issuing a credential to a digital wallet. Read more about Connectionless Credentials here.

  1. Offer Credential
  2. Request Credential
  3. Issue Credential

Our API offers two endpoints to accomplish the issuer initiated steps 1 & 3.

1. Send a credential offer

POST /credentials

{
"definitionId": "string",
"connectionId": "string",
"credentialValues": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
}
}

This will send a credential offer of the specified definitionId to the specified connectionId.

This offer will include a dictionary of credentialValues, which will be the values of the credential attributes.

Each key:value pair in the credentialValues object should correspond to the list of attributes in the specified definition.

The list of keys should match the attributeName list that is in the Credential definition.

2. Wait for a credential request

// you must now wait for the holder to accept the credential.
// you can use webhooks to be notified once the holder accepts, or
// get the credential record from your wallet to check for yourself.
credential = await client.getCredential(credential.credentialId);

3. Issue credential

PUT /credentials/{credentialId}

// The potential credential states are:
// 'Offered' | 'Requested' | 'Issued' | 'Rejected' | 'Revoked'
if(credential.state === 'Requested')
{
await client.issueCredential(credential.credentialId);
}

This simply needs the credential identifier. If the credential is in state requested, the credential will be issued to the digital wallet of the individual who accepted that offered credential.

Revoke a credential

A credential can be revoked by using the following commands:

await client.revokeCredential(credentialId);

Connectionless credentials

POST /credentials

{
"definitionId": "string",
"credentialValues": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
}
}

This will create a connectionless credential offer of the specified definitionId that will be returned as a link called offerUrl.

This offer will include a dictionary of credentialValues, which will be the values of the credential attributes.

Each key:value pair in the credentialValues object should correspond to the list of attributes in the specified definition.

The list of keys should match the attributeName list that is in the Credential definition.