Skip to content

Credential Service

The Credentials Service gives you the ability to manage complex workflows related to DIDs (contacts/Connections) and VCs (credential issuance, Revocation, Verification, etc). This is probably the service you will most interact with because VC Issuance and verification are at the core of every SSI use case.

The Credential service supports signing data using BBS+ Signatures . The data is signed with a key unique to the owner's wallet. This key is also used as linked secret, when it comes to proof derivation.

Issue Credential

Issues a credential from a valid JSON-LD document. You can learn more about how creating these documents, and about VC data models in general, from W3C: VC Data Model v1.1.

IssueCredential requires a valid JSON-LD document to be provided. Do not confuse this operation with Issue Credential From Template.

trinsic vc issue --document <JSONLD_FILE> --out <OUTPUT_FILE>

When using one of the SDKs, you must supply an Issue Request object. This object follows the model below:

Request to sign a JSON-LD Credential using public key tied to caller

Field Type Description
document_json string Valid JSON-LD Credential document to be signed, in string form

Then you can supply it to SDK:

// Sign a credential as the clinic and send it to Allison
const credentialJson = getVaccineCertUnsignedJSON();
const credential = await credentialService.issueCredential(
  IssueRequest.fromPartial({ documentJson: credentialJson })
);
var credential = await credentialsService.IssueCredentialAsync(new() {DocumentJson = credentialJson});
_testOutputHelper.WriteLine($"Credential:\n{credential.SignedDocumentJson}");
issue_response = await credentials_service.issue_credential(
    request=IssueRequest(document_json=credential_json)
)
credential, err := credentialService.IssueCredential(context.Background(), &sdk.IssueRequest{DocumentJson: string(fileContent)})
var issueResult = credentialsService.issueCredential(VerifiableCredentials.IssueRequest.newBuilder().setDocumentJson(credentialJson).build()).get();

The output of this method will be a signed JSON document using BBS+ Signature Suite 2020. This document is not automatically stored in the wallet when issued. You need to call the insert record separately if you'd like to store a copy of this document.

The response model is of type Issue Response:

Response to IssueRequest

Field Type Description
signed_document_json string Verifiable Credential document, signed with public key tied to caller of IssueRequest

Issue Credential from Template

Issues a credential from a previously defined template through CreateCredential call. The template is specified by passing a JSON document that matches the structure of the template. For example:

{
    "field1": "value1",
    "field2": "value2",
    ...
}

Do not confuse this operation with Issue Credential where JSON-LD document is required..

trinsic vc issue-from-template [OPTIONS] --template-id <ID>

# OPTIONS
# --out <OUTPUT_FILE>     (Optional) Output file to store the issued credential
# --values-data <JSON>    The JSON values of the credential subject
# --values-file <FILE>    The file with JSON values of the credential subject

When using one of the SDKs, you must supply an Issue From Template Request object. This object follows the model below:

Request to create and sign a JSON-LD Verifiable Credential from a template using public key tied to caller

Field Type Description
template_id string ID of template to use
values_json string JSON document string with keys corresponding to the fields of the template referenced by template_id
framework_id string Governance framework ID to use with issuance of this credential. If specified, the issued credential will contain extended issuer metadata with membership info for the given ecosystem governance framework (EGF)

Then you can supply it to SDK:

let request = IssueFromTemplateRequest.fromPartial({
  templateId: templateResponse?.data?.id ?? "",
  valuesJson: JSON.stringify({
    name: "Alice",
    numberOfBags: 2,
    dateOfBirth: new Date("1/1/2000").toISOString(),
    vaccinated: true,
  }),
});

let response = await service.issueFromTemplate(request);
var credentialJson = await credentialService.IssueFromTemplateAsync(new() {
    TemplateId = template.Data.Id,
    ValuesJson = values
});
values = json.dumps({"firstName": "Jane", "lastName": "Doe", "age": "42"})
issue_response = await credential_service.issue_from_template(
    request=IssueFromTemplateRequest(
        template_id=template.data.id, values_json=values
    )
)
credentialJSON, err := credentialService.IssueFromTemplate(context.Background(), &sdk.IssueFromTemplateRequest{
    TemplateId: template.Data.Id,
    ValuesJson: string(valuesString),
})
var valuesMap = new HashMap<String, Object>();
valuesMap.put("firstName", "Jane");
valuesMap.put("lastName", "Doe");
valuesMap.put("age", 42);
var valuesJson = new Gson().toJson(valuesMap);
var issueResponse = credentialService.issueCredentialFromTemplate(VerifiableCredentials.IssueFromTemplateRequest.newBuilder().setTemplateId(template.getData().getId()).setValuesJson(valuesJson).build()).get();

The output of this method will be a signed JSON document using BBS+ Signature Suite 2020. This document is not automatically stored in the wallet when issued. You need to call the insert record separately if you'd like to store a copy of this document.

The response model is of type Issue From Template Response:

Response to IssueFromTemplateRequest

Field Type Description
document_json string Verifiable Credential document, in JSON-LD form, constructed from the specified template and values; signed with public key tied to caller of IssueFromTemplateRequest

Check Revocation Status

Get the credential status (revocation) of a previously issued credential. You must supply the credential id to this call.

trinsic vc get-status --credential-status-id <ID>

When using one of the SDKs, you must supply an Check Status Request object. This object follows the model below:

Request to check a credential's revocation status

Field Type Description
credential_status_id string Credential Status ID to check

Then you can supply it to SDK:

var checkResponse = await credentialService.CheckStatusAsync(new() {CredentialStatusId = ""});
#     check_response = await credential_service.check_status(
#         request=CheckStatusRequest(credential_status_id="")
#     )
status, err := credentialService.CheckStatus(context.Background(), &sdk.CheckStatusRequest{CredentialStatusId: ""})
var checkStatusResponse = credentialService.checkStatus(VerifiableCredentials.CheckStatusRequest.newBuilder().build()).get();

The response model is of type Check Status Response:

Response to CheckStatusRequest

Field Type Description
revoked bool The credential's revocation status

Update Revocation Status

Update the credential status (revocation) of a previously issued credential. You must supply the credential id to this call.

# Revoke a credential
trinsic vc update-status --revoked --credential-status-id <ID>

# Unrevoke a credential
trinsic vc update-status --unrevoked --credential-status-id <ID>

When using one of the SDKs, you must supply an Update Status Request object. This object follows the model below:

Request to update a credential's revocation status

Field Type Description
credential_status_id string Credential Status ID to update
revoked bool New revocation status of credential

Then you can supply it to SDK:

await credentialService.UpdateStatusAsync(new() {CredentialStatusId = "", Revoked = true});
#     update_response = await credential_service.update_status(
#         request=UpdateStatusRequest(credential_status_id="", revoked=True)
#     )
updateResponse, err := credentialService.UpdateStatus(context.Background(), &sdk.UpdateStatusRequest{CredentialStatusId: "", Revoked: true})
credentialService.updateStatus(VerifiableCredentials.UpdateStatusRequest.newBuilder().build());

The response model is of type Update Status Response:

Response to UpdateStatusRequest

Create Proof

Wallets allow data to be shared between parties in a secure manner, using a technique called Zero Knowledge Proofs. Trinsic Ecosystems uses the BBS+ Signature Proof scheme to allow data to be selectively disclosed to the requesting party. This allows users to share only the requested subset of data, instead the entire document.

The endpoint to create a proof requires two inputs:

  • document in the wallet that is signed with the correct signature
  • JSONLD frame that describes the data to be disclosed
trinsic vc create-proof --document-id <STRING> --out <OUTPUT_FILE> --reveal-document <JSONLD_FRAME_FILE>

When using one of the SDKs, you must supply an Create Proof Request object. This object follows the model below:

Request to create a proof for a Verifiable Credential using public key tied to caller. Either item_id or document_json may be provided, not both.

Field Type Description
reveal_document_json string A valid JSON-LD frame describing which fields should be revealed in the generated proof. If unspecified, all fields in the document will be revealed
item_id string ID of wallet item stored in a Trinsic cloud wallet
document_json string A valid JSON-LD Verifiable Credential document string with an unbound signature. The proof will be derived from this document directly. The document will not be stored in the wallet.

Then you can supply it to SDK:

let proof = await credentialService.createProof(
  CreateProofRequest.fromPartial({
    itemId: insertItemResponse.itemId,
    revealDocumentJson: getVaccineCertFrameJSON(),
  })
);
var proof = await credentialService.CreateProofAsync(new() {
    DocumentJson = credentialJson.DocumentJson,
    RevealDocumentJson = frame.ToString(Formatting.None)
});
proof_response = await credentials_service.create_proof(
    request=CreateProofRequest(
        reveal_document_json=proof_request_json, item_id=item_id
    )
)
credentialProof, err := credentialService.CreateProof(context.Background(), req)
var createProofResponse = credentialsService.createProof(VerifiableCredentials.CreateProofRequest.newBuilder().setItemId(itemId).setRevealDocumentJson(proofRequestJson).build()).get();

The response model is of type Create Proof Response:

Response to CreateProofRequest

Field Type Description
proof_document_json string Valid JSON-LD proof for the specified credential

Verify Proof

This endpoint verifies if the submitted data contains a valid proof. The data to be verified must contain a Linked Data Proof with BBS+ signature scheme.

# The JSONLD_FILE refers to the proof document obtained from a CreateProofResponse
trinsic vc issuer verify-proof --proof-document <JSONLD_FILE>

When using one of the SDKs, you must supply an Verify Proof Request object. This object follows the model below:

Request to verify a proof

Field Type Description
proof_document_json string JSON-LD proof document string to verify

Then you can supply it to SDK:

let verifyResponse = await credentialService.verifyProof({
  proofDocumentJson: proof.proofDocumentJson,
});
var valid = await credentialService.VerifyProofAsync(new() {ProofDocumentJson = proof.ProofDocumentJson});
verify_result = await credentials_service.verify_proof(
    request=VerifyProofRequest(proof_document_json=credential_proof)
)
valid, err := credentialService.VerifyProof(context.Background(), &sdk.VerifyProofRequest{ProofDocumentJson: credential.SignedDocumentJson})
var verifyProofResponse = credentialsService.verifyProof(VerifiableCredentials.VerifyProofRequest.newBuilder().setProofDocumentJson(credentialProof).build()).get();

The response model is of type Verify Proof Response:

Response to VerifyProofRequest

Field Type Description
is_valid bool Whether or not all validations in validation_results passed
validation_messages string[] Deprecated. Use validation_results instead
validation_results VerifyProofResponse.ValidationResultsEntry[] Results of each validation check performed, such as schema conformance, revocation status, signature, etc. Detailed results are provided for failed validations.

Exchange Credentials

Exchanging data securely is one of the fundamental functions of digital identity systems. There are many specifications with varying maturity that aim to provide interoperable and secure way of exchanging authentic data. We are commited to providing support for these methods.

During this beta period, we are only supporting exchanging data between users by using their email addresses. The messages are routed securely to the destination wallet without leaving the secure network of the ecosystem backend. Our goal is to provide basic ability to share data without affecting the user experience. As interoperable exchange methods become available, we will add this functionality in the SDK.

Sending documents using Email as identifier

To send a document to another user, they must have created a wallet and associated their email address with that wallet.

trinsic vc send --email <EMAIL_ADDRESS> --item <FILE>

When using one of the SDKs, you must supply an Send Request object. This object follows the model below:

Request to send a document to another user's wallet

Field Type Description
email string Email address of user to send item to
did_uri string DID of recipient (presently unsupported)
didcomm_invitation_json string DIDComm out-of-band invitation JSON (presently unsupported)
document_json string JSON document to send to recipient

Then you can supply it to SDK:

await credentialService.send(document, "[email protected]");
await credentialsService.SendAsync(new() {Email = "[email protected]"});
send_response = await credentials_service.send(
    request=SendRequest(document_json=credential, email="[email protected]")
)
err = credentialService.Send(context.Background(), &sdk.SendRequest{DocumentJson: credential.SignedDocumentJson,
    DeliveryMethod: &sdk.SendRequest_Email{Email: "[email protected]"}})
credentialsService.send(VerifiableCredentials.SendRequest.newBuilder().setDocumentJson(credentialProof).setEmail("[email protected]").build());

The response model is of type Send Response:

Response to SendRequest