LogoLogo
ProductsCommunityGitHubShare Feedback
SSI Kit
SSI Kit
  • General
    • Introduction
    • Transition To The Community Stack
    • SSI Kit | Basics
      • Overview
      • Functionality
      • Components
    • SSI Kit
      • SSI Flavors & Ecosystems
        • Trust Registries
        • Keys
        • Decentralized Identifiers (DIDs)
        • Verifiable Credentials (VCs)
        • Data Exchange Protocols
      • Architecture
        • Low-Level Service Abstraction
        • Ecosystem Abstraction
        • High-Level Interfaces / APIs
      • Use Cases
      • Self-Sovereign Identity (SSI)
        • SSI | Basics
        • Technologies & Concepts
          • Registries
          • Decentralised Identifiers (DIDs)
          • Verifiable Credentials (VCs)
          • Verifiable Presentations (VPs)
          • Data Exchange (Protocols)
  • Getting started
    • Quick Start
    • REST API
      • Signatory API - For Issuers
      • Custodian API - For Holders
        • Key management
        • Did management
        • Credentials management
      • Auditor API - For Verifiers
      • Core API
        • Cryptographic keys
        • Decentralised-Identifiers
        • Verifiable-Credentials
      • API Serving Configs
    • Dependency (JVM)
      • Java Examples
      • Kotlin Examples
    • CLI | Command Line Interface
      • Key Management
      • Decentralized Identifiers
      • Verifiable Credentials
      • OpenID Connect (OIDC)
    • Building the Project
      • Docker Build
      • Local Build
    • Project Configurations
    • Demo
  • Ecosystems
    • EBSI
      • Basics
      • Use Cases & Flow Diagrams
      • Command line interface
        • DID Registration
      • REST API
      • Usage / examples
        • Onboarding & DIDs
        • Build end-to-end use cases
    • IOTA
      • OIDC4VP profile for Login-with-IOTA
      • Login With IOTA Demo
    • Velocity
      • Basics
        • Onboarding
        • Issuing
        • Inspection
      • Integration with SSIKit
      • Command line interface
        • Onboarding
        • Issuing
        • Inspection
    • cheqd
      • Integration architecture
      • Create DID
      • Issue VC
      • Verify VC
  • Tutorials
    • My First VC
    • Advanced VC
  • Concepts
    • Credential Templates
    • Verification Policies
      • Static Policies
      • Parameterized Policies
      • Dynamic/Custom Policies
        • Creating Dynamic Policies
        • Using Dynamic Policies
        • Removing Dynamic Policies
        • Dynamic Policies | Data Classes
    • Selective Disclosure
      • Intro
      • Issuing a SD-JWT Credential
      • Verifying a SD-JWT Credential
    • Credential Statuses
      • StatusList2021Entry
      • SimpleCredentialStatus2022
      • Issue credentials with credentialStatus
      • REST API
        • Check the status of a credential
        • Revoke a credential
      • CLI
        • Check the status of a credential
        • Revoke a credential
    • DID Web
    • Open Policy Agent (OPA)
      • Setup
    • OpenID Connect (OIDC)
      • Credential Issuance
        • OIDC4CI | Example
      • Presentation Exchange
        • OIDC4VP | Example
    • Delegation and Mandates
  • Community
    • Discord
    • Twitter
    • Newsletter
    • GitHub Discussions
  • DEVELOPER RELATIONS
    • Contribute
    • Roadmap
    • Share Feedback
    • Contact
  • Product Editions
    • Open Source | Always Free
    • Enterprise | Self-Managed
    • Cloud Platform | Managed
Powered by GitBook
On this page

Was this helpful?

Export as PDF
  1. Tutorials

My First VC

PreviousVerify VCNextAdvanced VC

Last updated 1 month ago

Was this helpful?

In this tutorial, our fictional SSI Use-Case involves Emma, a recent university graduate, who wants to apply for a job. The employer requires proof of her academic credentials. To achieve this, she will use her Verifiable Degree Credential issued by her university.

Where we start:

Utilizing the walt.id SSI-Kit's REST-API, we will provide Emma with the Verifiable Degree Credential by creating a DID for both the university (Issuer) and Emma (Holder). After that, the employer (Verifier) will authenticate the Degree Credential using the associated DIDs.

What we do:

  1. - for Emma + University

  2. to Emma

  3. from Emma

Running the SSI-Kit

Make sure you have Docker or a JDK 16 build environment including Gradle installed on your machine

Pull the docker container directly from docker hub and run the project

docker run -p 7000-7004:7000-7004 -itv $(pwd)/data:/app/data waltid/ssikit serve -b 0.0.0.0

This will create a folder called data in your current directory as storage for the VC, DIDs, Keys and other things which need to be stored in order to provide all the functionality.

  1. Clone the project

git clone https://github.com/walt-id/waltid-ssikit.git

2. Change the folder

cd waltid-ssikit/

3. Run the project

The first time you run the command you will be asked to built the project. You can confirm the prompt.

./ssikit.sh serve

Now with the project up and running, visit the URL displayed in your terminal. We will use it, to create our first DID (Decentralised Identifier). If you want to learn more about DIDs, visit the

Creating the DIDs

curl -X 'POST' \
  'http://localhost:7002/did/create' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "method": "{method}"
}'

Body Parameters method: [string] method of the did. Value can be one of key, web, ebsi, iota, cheqd, jwk Example

curl -X 'POST' \
  'http://localhost:7002/did/create' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "method": "key"
}'

Create DIDs for the University (Issuer) and Emma (Holder) using the example above twice. Make sure to save the DIDs somewhere, as we will be needing them later for the issuance of the credential.

Issuing a Verifiable University Degree Credential

{
  "type": ["VerifiableCredential", "UniversityDegreeCredential"],
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://www.w3.org/2018/credentials/examples/v1"
  ],
  "id": "http://example.gov/credentials/3732",
  "issuer": {
    "id": "did:example:456"
  },
  "issuanceDate" : "2023-03-21T15:35:08Z",
  "issued" : "2023-03-21T15:35:08Z",
  "validFrom" : "2023-03-21T15:35:08Z",
  "credentialSubject": {
    "id": "did:example:123",
    "degree": {
      "name": "Bachelor of Science and Arts",
      "type": "BachelorDegree"
    }
  },
  "proof" : {
    "type" : "JsonWebSignature2020",
    "creator" : "did:example:456",
    "created" : "2023-03-21T15:35:08Z",
    "verificationMethod" : "did:example:456",
    "jws" : "eyJiNjQiOmZhbHNlLCJjcml0IjpbImI2NCJdLCJhbGciOiJFZERTQSJ9..zDI3Wc6jWN7288tlat3LohWsoZiIkBODvlmLPtCy49vUZxpv1NYtZNCMd5Z4RxVQSSbkjPSDzDfAmlOBLhUZBg"
  }
}

This Verifiable Diploma includes the following key elements:

  • "type": Defines the credential as both a general "VerifiableCredential" and a more specific "UniversityDegreeCredential".

  • "@context": Provides references to the necessary standards and examples for interpreting the credential.

  • "id": A unique identifier for the credential.

  • "issuer": The DID of the university issuing the diploma (e.g., "did:example:456").

  • "issuanceDate": The timestamp indicating when the credential was issued.

  • "issued": The timestamp indicating when the credential was issued.

  • "validFrom": The timestamp indicating from when the credential is valid.

  • "credentialSubject": Contains the DID of the credential holder (Emma - e.g., "did:example:123") and the details of the degree earned, such as the name of the degree and its type.

  • proof: The proof object contains the digital signature and related information that is used to verify the authenticity and integrity of the Verifiable Credential.

    • type: "JsonWebSignature2020" indicates the cryptographic suite used for generating the digital signature. In this case, it's the JSON Web Signature (JWS) standard based on the Ed25519 signature algorithm.

    • creator: "did:example:456" is the DID of the entity that created the digital signature, in this case, the issuer of the Verifiable Credential.

    • created: "2023-03-21T15:35:08Z" is the timestamp when the digital signature was created. It is in the ISO 8601 format.

    • verificationMethod: "did:example:456" is the identifier for the public key or cryptographic method used to verify the digital signature.

    • jws: is the actual digital signature (JWS) generated using the Ed25519 algorithm. This signature is used to verify the authenticity and integrity of the Verifiable Credential.

Now that we know how the credential looks like, let's issue it.

Issue

curl -X 'POST' \
  'http://localhost:7001/v1/credentials/issue' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "templateId": "{template type}",
  "config": {
    "issuerDid": "{issuerDid}",
    "subjectDid": "{subjectDid}",
    "proofType": "{proofType}"
  },
  "credentialData": {
    "id": "{subjectDid}",
    "degree": {
      "name": "{Degree name}",
      "type": "{Degree type}"
    }
  }
}'

Body Parameters

  • templateId: [string] The identifier of the template used for issuing a Verifiable Credential. This template defines the structure and format of the credential being issued.

  • config: [object] Contains configuration parameters for the issuance process.

    • issuerDid: [string] The DID of the entity issuing the credential (University).

    • subjectDid: [string] The DID of the entity receiving the credential (Emma).

    • proofType: [string] Specifies the format and cryptographic algorithm used for the digital signature of the Verifiable Credential. E.g. LD_PROOF

  • credentialData: [object] Contains the actual data of the credential being issued.

    • credentialSubject: [object] Holds the information about the credential holder and the earned degree.

      • id: [string] The DID of the credential holder, identical to the subjectDid in the config object.

      • degree: [object] Contains details of the degree earned by the credential holder.

        • name: [string] The name of the earned degree (e.g., "Bachelor of Science and Arts").

        • type: [string] The type of the earned degree (e.g., "BachelorDegree").

Example:

curl -X 'POST' \
  'http://localhost:7001/v1/credentials/issue' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "templateId": "UniversityDegree",
  "config": {
    "issuerDid": "did:key:z6MkmE21F2dAHkM71tnYdBEGaSvnPpxBFZYi2wtzYbTwqvgK",
    "subjectDid": "did:key:z6MkmE21F2dAHkM71tnYdBEGaSvnPpxBFZYi2wtzYbTwqvgK",
    "proofType": "LD_PROOF"
  },
  "credentialData": {
    "id": "did:key:z6MkmE21F2dAHkM71tnYdBEGaSvnPpxBFZYi2wtzYbTwqvgK",
    "degree": {
      "name": "Bachelor of Science and Arts",
      "type": "BachelorDegree"
    }
  }
}'

Awesome, you just issued your first VC 🎉. Now Emma can use it to prove her academic credentials to her employer.

Verify The University Degree Credential

Emma needs to verify her academic credentials to her employer, which involves the following steps performed by the verifier (employer):

  1. Verify the credential's digital signature: The Verifier checks if the digital signature on the credential is valid and has been signed by the Issuer's private key. This ensures that the credential was indeed issued by the claimed Issuer.

  2. Check the Issuer's DID: The Verifier validates the Issuer's Decentralized Identifier (DID) by resolving it to a DID Document. This step helps confirm the Issuer's identity and retrieve their public key for signature verification.

  3. Verify the Holder's DID: The Verifier checks the credential's subject (i.e., the Holder) by validating their DID. This ensures that the credential was issued to the correct entity and prevents unauthorized use of the credential.

  4. Check the credential's status: (Not for our use-case) The Verifier may also query the credential's status on a registry, ledger, or another trusted source. This step helps confirm whether the credential is still valid or has been revoked by the Issuer.

  5. Check the credential's integrity: The Verifier confirms that the credential data has not been tampered with since issuance. This is typically done by comparing the signed data with the credential's content to detect any discrepancies.

  6. Verify the credential's issuance and expiration dates: The Verifier checks the issuance and expiration dates (if applicable) of the credential to ensure it was issued within the specified time frame and is still valid.

curl -X 'POST' \
  'http://localhost:7003/v1/verify' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "policies": [
    {
      "policy": "SignaturePolicy"
    }
  ],
  "credentials": [{Emma's Credential}]
}'

Example

curl -X 'POST' \
  'http://localhost:7003/v1/verify' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "policies": [
    {
      "policy": "SignaturePolicy"
    }
  ],
  "credentials": [
    {
      "type": [
        "VerifiableCredential",
        "UniversityDegreeCredential"
      ],
      "@context": [
        "https://www.w3.org/2018/credentials/v1",
        "https://www.w3.org/2018/credentials/examples/v1",
        "https://w3id.org/security/suites/jws-2020/v1"
      ],
      "id": "urn:uuid:a78bcd04-183b-4e57-91fe-954cb8dc6a04",
      "issuer": {
        "id": "did:key:z6MkgjQxcoh1JWXMgG7xPNeBaqUXWu42LAW8G5KmE7J6d1CG"
      },
      "issuanceDate": "2023-03-21T15:54:16Z",
      "issued": "2023-03-21T15:54:16Z",
      "validFrom": "2023-03-21T15:54:16Z",
      "credentialSubject": {
        "id": "did:key:z6MkgjQxcoh1JWXMgG7xPNeBaqUXWu42LAW8G5KmE7J6d1CG",
        "degree": {
          "name": "Bachelor of Science and Arts",
          "type": "BachelorDegree"
        }
      },
      "degree": {
        "name": "Bachelor of Science and Arts",
        "type": "BachelorDegree"
      },
      "proof": {
        "type": "JsonWebSignature2020",
        "creator": "did:key:z6MkgjQxcoh1JWXMgG7xPNeBaqUXWu42LAW8G5KmE7J6d1CG",
        "created": "2023-03-21T15:54:16Z",
        "verificationMethod": "did:key:z6MkgjQxcoh1JWXMgG7xPNeBaqUXWu42LAW8G5KmE7J6d1CG#z6MkgjQxcoh1JWXMgG7xPNeBaqUXWu42LAW8G5KmE7J6d1CG",
        "jws": "eyJiNjQiOmZhbHNlLCJjcml0IjpbImI2NCJdLCJhbGciOiJFZERTQSJ9..9LiRH2WXqAWIgA54PJ3Qt6ECOSykuU2b_n7UTA-2otZqX-sNP79VgZ5cBlLZeUTis90pAtsRS5uoAblxWjwcDg"
      }
    }
  ]
}'

You have successfully issued and verified a Verifiable Credential. Great job!! Emma can start her new job 🎉 Where to go next?

Using the DIDs from the previous step, we will now issue a University Degree Credential. To issue the credential, we will be using the . Below you find the final credential structure. Verifiable Diploma

To verify the credential, we will be using the endpoint.

Exploring ssi-kit Capabilities - Familiarize yourself with the various features of ssi-kit by reviewing the or section.

- Discover the potential applications of Verification Policies and how they can be useful for your particular use-case.

- Visit our ecosystem overview page to explore the different ecosystems (did:methods) that we support.

Signatory API endpoint
Auditor API
REST API
Command Line
Understanding Verification Policies
Exploring Supported Ecosystems
walt.id Custodian API
general section.
Run the SSI-Kit and expose API
Create DIDs
Issue Credential
Verify Credential