Quick start guide

This guide will walk you through the process of creating and verifying a verifiable credential (VC) using the Truvity SDK. You will utilize User Defined Types (UDTs) to represent the credential claims schema, enhancing type safety and simplifying the credential lifecycle.

Prerequisites

Before you begin, make sure you have the following:

• Installed and configured Truvity SDK. If you do not have the installed SDK, follow the Installation guide.
• A basic understanding of Self-Sovereign Identity (SSI) concepts, such as Decentralized Identifiers (DIDs), Verifiable Credentials (VCs), and Verifiable Presentations (VPs). For more information, refer to the Core Concepts section.

Step 1: Define a simple credential type

Let's begin by defining a simple credential type using UDTs. This credential type contains two required claims: name and age.

TypeScript

import { Truvity, VcContext, VcClaim } from '@truvity/sdk';

// Define a simple credential type using UDT
@VcContext({ name: 'SimpleCredential', namespace: 'https://example.com/credentials' })
class SimpleCredential {
    @VcClaim
    name?: string;

    @VcClaim
    age?: number;
}

Java

import com.truvity.api.documents.annotations.VcContext;
import lombok.Data;

@Data
@VcContext(name = "SimpleCredential", namespace = "https://example.com/credentials")
public static class SimpleCredential {
    private Optional<String> name;

    private Optional<Integer> age;
}

The @VcContext decorator defines the credential type and its namespace. The @VcClaim decorator marks the fields as claims in the credential.

Step 2: Generate a key for signing

To issue a credential, you first need to generate a cryptographic key. In this case, we are using the ED25519 key type.

TypeScript

const key = await client.keys.keyGenerate({ data: { type: 'ED25519' } });

Java

KeyResource key = client.keys()
        .keyGenerate(KeyGenerateInput.builder()
                .data(KeyGenerate.builder().type("ED25519").build())
                .build());

This key will be used to sign the credential later in the process.

Step 3: Create a draft

Now, let's create a draft using the SimpleCredential UDT that we defined in Step 1. This draft includes the claims (name and age) that we want to embed in the credential.

info

Draft is a concept introduced by Truvity that represents the initial state of credential's content. To learn more about drafts, check the Drafts vs credentals page.

TypeScript

const simpleCredDecorator = client.createVcDecorator(SimpleCredential);

const draft = await simpleCredDecorator.create({
    claims: {
        name: "Alice",
        age: 30
    }
});

Java

VcDecorator<SimpleCredential> simpleCredDecorator = client.vcDecorator(SimpleCredential.class);

SimpleCredential simpleCredentialData = new SimpleCredential();
simpleCredentialData.setName("Alice");
simpleCredentialData.setAge(30);

var draft = simpleCredDecorator.create(simpleCredentialData);

In this step, the credential is not yet issued or signed — it is just a draft that contains the claims data.

Step 4: Issue the credential

Next, we issue the credential by signing it with the previously generated key. This transforms the draft into a verifiable credential (VC).

TypeScript

const issuedVC = await draft.issue(key.id);

Java

var issuedVC = draft.issue(key.getId());

The issued credential is now cryptographically signed and can be shared with other parties.

Step 5: Verify the credential

Finally, verify the authenticity of the issued credential. Verification ensures that the credential has not been tampered with and that it was signed by a valid key.

TypeScript

const verificationResult = await issuedVC.verify();
console.log("Verification result:", verificationResult.verified);

Java

var verificationResult = issuedVC.verify();
System.out.println(verificationResult.verified());

The verify() function checks the integrity and validity of the credential, and the result is printed to the console.

Putting it all together

Now that we have broken down each step, here is the full code that puts everything together. This code defines a credential, generates a key, creates a draft, issues the credential, and finally verifies it.

TypeScript

import { TruvityClient, VcContext, VcClaim } from '@truvity/sdk';

// Define a simple credential type using UDT
@VcContext({ name: 'SimpleCredential', namespace: 'https://example.com/credentials' })
class SimpleCredential {
    @VcClaim
    name!: string;

    @VcClaim
    age!: number;
}

async function createAndVerifyVC() {
    // Initialize the SDK client
    const client = new Truvity.TruvityClient({
        environment: "https://api.truvity.cloud",
        apiKey: "YOUR_API_KEY",
    });

    // Generate a key for signing
    const key = await client.keys.keyGenerate({ data: { type: 'ED25519' } });

    // Create a credential decorator
    const simpleCredDecorator = client.createVcDecorator(SimpleCredential);

    // Create a draft
    const draft = await simpleCredDecorator.create({
        claims: {
            name: "Alice",
            age: 30
        }
    });

    // Issue the credential
    const issuedVC = await draft.issue(key.id);

    // Verify the credential
    const verificationResult = await issuedVC.verify();
    console.log("Verification result:", verificationResult.verified);
}

createAndVerifyVC();

Java

// Define a simple credential type using UDT
@Data
@VcContext(name = "SimpleCredential", namespace = "https://example.com/credentials")
public static class SimpleCredential {
    private Optional<String> name;

    private Optional<Integer> age;
}

void createAndVerifyVC() {
    // Initialize the SDK client
    TruvityApiExtendedClient client = new TruvityApiExtendedClientBuilder()
                .environment(Environment.custom("https://api.truvity.cloud"))
                .apiKey(System.getenv("YOUR_API_KEY")).build();

    // Generate a key for signing
    KeyResource key = client.keys()
            .keyGenerate(KeyGenerateInput.builder()
                    .data(KeyGenerate.builder().type("ED25519").build())
                    .build());

    // Create a credential decorator
    VcDecorator<SimpleCredential> simpleCredDecorator = client.vcDecorator(SimpleCredential.class);

    SimpleCredential simpleCredentialData = new SimpleCredential();
    simpleCredentialData.setName("Alice");
    simpleCredentialData.setAge(30);

    // Create a draft
    var draft = simpleCredDecorator.create(simpleCredentialData);

    // Issue the credential
    var issuedVC = draft.issue(key.getId());

    // Verify the credential
    var verificationResult = issuedVC.verify();
    System.out.println(verificationResult.verified());
}

Congratulations! You have just issued your first Truvity-powered verifiable credential and is now ready to explore more topics on working with the SDK.

Further reading

• Cover the full credential lifecyclefrom creating a credential to sharing it with the verifier.
• Learn how to link credentials to each other and files to credentials.
• Epxlore how to manage credential data by modeling credential data with labels, using faceted search to retrieve results, and viewing credential history.