Here are the most important things you need to know about the SSI Kit:

• It is written in Kotlin/Java. It can be directly integrated (Maven/Gradle dependency) or run as RESTful web-service. A CLI tool allows you to run all functions manually.

• It is open source (Apache 2). You can use the code for free and without strings attached.

• It is a holistic solution that allows you to build use cases “end-to-end”. There is no need to research, combine or tweak different libraries to build pilots or production systems.

• It abstracts complexity and low-level functionality via different interfaces (CLI, APIs). Additional services facilitate development and integration (e.g. Issuer and Verifier Portals).

• It is modular, composable and built on open standards allowing you to customize and extend functionality with your own or third party implementations and to preventing lock-in.

• It is flexible in a sense that you can deploy and run it on-premise, in your (multi) cloud environment or as a library in your application.

• It enables you to use different identity ecosystems like Europe’s emerging identity ecosystem (EBSI, ESSIF) in anticipation of a multi-ecosystem future.

The SSI Kit offers everything you need to use Self-Sovereign Identity (SSI) with ease.

The following sections elaborate the SSI Kit's unique properties, enabled functionality and components.

The Community Stack

It has always been our goal to provide developers and organizations with great tools, so they can focus on delivering holistic identity solutions. Taking the lessons learned from previous products, we decided to redesign our current offering, resulting in what we now call The Community Stack. A collection of open-source products providing everything to launch any identity solution with ease. You can learn more about it here.

Transition

Starting from December 2023, the SSI-Kit will halt feature enhancements, leading to a complete discontinuation planned for end-Q3 2024. It's essential to plan your transition to the new stack effectively. The table below indicates which components of the SSI-Kit are already supported in the new stack.

• For Kotlin/Java projects where SSI-Kit was used as a native dependency, utilize the provided Library for equivalent features in the new stack. •

• If you employed the REST APIs, simply switch to the supplied API in the new stack.

If you have any question, please reach out.

Signatory | For Issuers

Signatory allows you to digitize paper credentials and automate data provision to your stakeholders.

It provides all functionality required by “Issuers”. For example:

• Process and authenticate data requests by people or organisations,

• Import data (from local storage or third parties),

• Create re-usable VC templates,

• Create VCs in different formats (e.g. JSON/JWT, JSON-LD),

• Sign VCs using different key types (e.g. ed25519, secp256K1, RSA),

• Manage the lifecycle of VCs (e.g. revocation).

• Issue VCs (e.g. via OIDC/SIOP)

Custodian | For Holders

Custodian is a secure data hub for people and organizations. It provides all functionality required by “Holders”. For example:

• Interact with Registries (read, write)

• Create, store, manage keys, data (DIDs, VCs) and other secrets,

• Request and import data (VCs) from third parties,

• Selectively disclose data (VCs/VPs) for authentication and identification,

• Manage consent and data access in a user-centric fashion.

Auditor | For Verifiers

Auditor allows you to verify your stakeholders’ identity data and offer frictionless access to services or products. It provides all functionality required by “Verifiers”. For example:

• request data (VCs/VPs) from stakeholders,

• verify data (VCs/VPs; incl. integrity, validity, provenance, authenticity),

• trigger pre-defined actions following the verification.

Verification Policies

The verification steps can be dynamically configured by passing "verification policies" to each verification attempt.

The SSI Kit comes with the following set of built-in verification polices:

• SignaturePolicy: Loads or resolves DID, loads public key and verifies the credentials signature.

• JsonSchemaPolicy: Validates the credential against the JSON schema.

• TrustedSchemaRegistryPolicy: Checks if the JSON schema is anchored in the EBSI Trusted Schema Registry.

• TrustedIssuerDidPolicy: Checks if the issuer DID is anchored on the EBSI DID registry.

• TrustedIssuerRegistryPolicy: Checks if the issuer got inserted in the EBSI TIR (Trusted Issuer Registry).

• TrustedSubjectDidPolicy: Checks if the issuer DID is anchored on the EBSI DID registry.

• IssuedDateBeforePolicy: Checks if issued date is in the past.

• ValidFromBeforePolicy: Checks if valid-from date is in the past.

• ExpirationDateAfterPolicy: Checks if expiration-date is in the futrue.

• CredentialStatusPolicy: Checks if credential is revoked based on the credential-status list.

The SSI Kit establishes an identity infrastructure layer for any use case in any industry. Its core services are in the scope of:

• Registry Interactions (e.g. read, write; agnostic towards the underlying tech e.g. DLT, DNS)

• Key Management (e.g. generate, sign, import, export, manage lifecycle)

• Decentralized Identifier (DID) operations (e.g. register, resolve, manage lifecycle)

• Verifiable Credential/Presentations (VC, VP) operations (e.g. create, issue, present, verify)

• Ecosystem specific use cases (e.g. onboarding, data exchange and monetization)

Illustration:

This documentation will help you understand how the SSI Kit works and how you can use it. However, it presumes a certain level of knowledge about Self-Sovereign Identity (SSI) so

Cryptographic keys convey control over digital identities and enable core functionality such as encryption and authentication.

The SSI Kit supports:

• EdDSA / ed25519

• ECDSA / secp256k1

• ECDSA / secp256r1

• RSA

Note that we are continuously adding support for new key types.

You can learn more about keys here.

Our open source solutions enable you to use different types of DIDs and different identity ecosystems. Every relevant functionality is supported from the generation of DIDs and DID Documents to anchoring or resolving them on/from Registries.

We currently support the following DID methods:

• did:ebsi

• did:web

• did:key

• did:jwk

• did:iota

• did:cheqd

Note that we are continuously adding support for new DID methods.

You can learn more about DIDs here.

Authentication and data exchange protocols (e.g. OIDC/SIOP) enable the exchange of data (VCs) between different parties.

The SSI Kit supports latest OpenID Connect extension for SSI:

• OpenID Connect for Credential Issuance (OpenID4CI)

• OpenID for Verifiable Presentations (OpenID4VP)

The implementation of the protocols is conformant with the latest specs from EBSI https://api-conformance.ebsi.eu/docs/wallet-conformance

You can learn more about protocols here.

This section elaborates the theory behind the SSI Kit:

• SSI Kit | Basics - Learn what the SSI Kit is and what it does.

• SSI Flavors & Ecosystems - Learn which SSI flavors and identity ecosystems we support.

• Architecture - Explore the SSI Kit's multi-layered architecture and components.

• Use Cases - Explore use cases you can implement with the SSI Kit.

• SSI-Kit feature list - Explore all features in an overview list.

The SSI Kit abstracts complexity for developers by following a "multi-stack approach" that enables you to use different implementations or "flavours" of SSI.

As a result, you can participate in different identity ecosystems (e.g. EBSI/ESSIF, Gaia-X, Velocity Network, cheqd and IOTA) and avoid technology-related lock-in effects.

Based on our Introduction to Self-Sovereign Identity (SSI), we distinguish the following concepts or building blocks:

Read on to learn which concrete technologies and implementations we support on the level of

• Trust Registries

• Keys

• Decentralized Identifiers (DIDs)

• Verifiable Credentials (VCs)

• Data Exchange Protocols

Our products are agnostic towards the underlying technologies used to implement Trust Registries, which means that the SSI Kit is potentially compatible with any type of Trust Registry.

The SSI Kit supports:

• Permissionless Blockchains (e.g. Ethereum),

• Permissioned Blockchains (e.g. Ethereum Enterprise/Hyperledger Besu),

• Domain Name Service (DNS),

• Pure peer-to-peer approaches that do not require Registries.

Note that we are continuously adding support for new Registries and underlying technologies.

You can learn more about Trust Registries here.

Verifiable Credentials (VCs) are digital identity documents that can easily and securely be shared with and verified (incl. validity, integrity, authenticity, provenance) by anyone in a privacy preserving way. Importantly, they are never (!) stored on a blockchain due to privacy and compliance reasons.

The SSI Kit supports W3C Verifiable Credentials in different formats:

• JSON / JWT

• JSON-LD

Note that we are continuously adding support for new VC types and formats.

You can learn more about VCs here.

The SSI Kit exposes high-level interfaces / APIs to hide the complex introduced by

• low-level services (e.g. key management, signing, data storage)

• different ecosystems (i.e. different SSI flavors, business logic and governance frameworks).

The functionality of the high-level interfaces correlate with the SSI Kit Components. The functions are grouped around:

• issuing Verifiable Credentials by the Signatory,

• holding (storing, presenting) Verifiable Credentials by the Custodian

• and verifying Verifiable Credentials by the Auditor.

The interfaces can be used in JVM-based applications directly, or via the REST API.

The Swagger documentation can be found under section REST API.

You can use Self-Sovereign Identity (SSI) - and by extension the SSI Kit - to solve any identity-related problem.

Identity and Access Management (IAM, CIAM)

You can use the SSI Kit to enable your users, customers, employees or partners to access information, services or products. By this, you can replace today's cumbersome sign-up and login processes (usernames, passwords) with more seamless experiences.

In other words, you can SSI to authenticate stakeholders you already know.

Identity Proofing / Verification

You can use the SSI Kit to identify people, organizations or even things to provide them with information, services or products.

Identity proofing is particularly important in the AML (anti-money launder) regulated industries, but is seeing growing adoption by non-regulated industries and platforms to prevent fraud, SPAM and other malicious behaviour.

Simply put, you can use SSI to identify stakeholders you do not yet know.

Risk and Compliance Checks

You can use the SSI Kit to verify any identity-related information beyond a person’s or company’s core identity (see Identity Proofing / Verification), which can be important when evaluating risks or performing compliance assessments.

For example, you can use SSI for

• employment background checks (education, work, criminal history)

• financial due diligence (bank account information, liquidity events, credit ratings)

• any other type of data verification required for transactions from insurance or health data to social proofs like ratings or recommendations.

Digital Credentials

SSI can be used to digitize any type of identity-related information in order to replace paper-based identity documents or cards with digital ones that are easier to manage, share and verify as well as harder to forge.

For example, think about official public sector documents such as identity certificates or about licenses or certificates that convey allowance to perform regulated activities.

You can find more examples in our White Papers:

• Introduction to Self-Sovereign Identity

• Me, Myself & (SS)I (co-authored by the Boston Consulting Group)

Identity Wallets

Any Questions

If you have any questions, feel free to get in touch.

The architecture of the SSI Kit consists of three layers:

1. Low-Level Services Abstraction: Abstracts complex, low-level operations (e.g. cryptography, key management, digital signatures, data storage).

2. Ecosystem Abstraction: Abstracts ecosystem-specific requirements based on the relevant technical and governance frameworks (e.g. SSI flavors, business logic, policies).

3. High-Level Interfaces / APIs: Provides high-level interfaces that hide complexity and facilitate usage for developers.

Also, the architecture allows for the integration of third party solutions throughout the stack. For example:

• Key storage (e.g. HSM, WebKMS)

• Data storage (e.g. identity hubs, confidential storage)

• Registries (e.g. blockchains, DNS)

This architectural openness prevents vendor lock-in and allows you to build SSI-based solutions that meet your unique requirements.

Illustration:

Read on to explore all three abstraction layers in more detail.

This software-layer holds a set of generic core services for common SSI and cryptographic functions. The services are in the scope of key management, decentralized identifiers, verifiable credentials and data storage.

The following is a short summary of the interfaces available. The detailed functions are described in the documentation further on.

Key Interfaces

Handles keys and cryptographic operations like the generation of signatures (e.g. linked data, JWT) with signature types such as ES256K or EdDSA.

Keys can be stored in a file and database keystore, which is extendable to HSMs and WebKMS.

DID Interfaces

Abstracts common functionality related to Decentralised Identifiers (DIDs, DID Documents) for methods like “did:web”, “did:key”, “did:ebsi”.

Credential Interfaces

Abstracts common functionality related to Verifiable Credentials (VCs) and Verifiable Presentations (VPs) in different formats like JSON and JSON-LD.

We believe in a multi-ecosystem future.

This is why we built an abstraction layer for ecosystem-specific operations and business logic. The idea is to support any ecosystem with a single solution that does not put any additional burden on developers. As a result, you can use our solutions to participate in different ecosystems without having to switch between different technical implementations.

We currently support:

• EBSI/ESSIF (EU's new decentralized identity ecosystem)

• Gaia-X (EU's new cloud infrastructure)

• Velocity Network

• cheqd Network

• IOTA

Note that we are continuously adding new ecosystems.

Different authentication and data exchange protocols are used to securely transfer identity data (e.g. VCs, VPs) between parties (e.g. from an Issuer to a Holder). They typically establish a mutually authenticated and encrypted data channel between the communicating parties.

The most common data exchange protocols used for SSI are:

• OIDC4SSI / SIOP (Self-Issued OpenID Connect Provider): An extension of a mature authentication and authorization protocol called "OpenID Connect" (OIDC).

• DIDComm: A novel protocol specifically designed for SSI and maintained by the Decentralized Identity Foundation (DIF).

• Credential Handler API: A proposed browser-extension that may be used to connect the user's identity wallet to a web-application.

DIDs are unique identifiers (URIs) which are standardised by the W3C. They can refer to any subject - from a person, to an organization, to a thing or basically anything else for that matter. Before we have a look at how a DID is structured and the benefit it provides, let's understand the shortcomings of current identifiers first and then see how the DID solves those.

The shortcomings of current IDs

In the digital economy, data exchange happens a lot, which makes it increasingly important to be able to identify persons, concepts or anything else for that matter in a secure and verifiable way.

A person today can have multiple different identifiers, like:

• name@surname.com

• https://www.surname.com

• 0000-0000-0000-0000 (ORCID based identifier, used to identify authors of scholarly communication)

All of these identifiers work, but none fulfills to be decentralized, persistent, resolvable and cryptographically verifiable when put into the following questions.

Is the identifier decentralized?

• https://www.surname.comdepends on a single point of failure. What happens if the hosting side disappears?

• 0000-0000-0000-0000 (ORCID) depends on the ORCID database. What happens if it is discontinued, hacked, etc?

Is the identifier persistent?

• https://www.surname.com If I do no longer pay for that domain, the identifier will be gone or even bought by somebody else.

Is the identifier resolvable?

• How can I get additional information about 0000-0000-0000-0000 (ORCID) identifiers?

Is the identifier verifiable?

• How can I prove that I own the domain, https://www.surname.com?

• If I stopped paying for my domain, https://www.surname.com and somebody else would buy it. How would somebody know that the information provided on the side was actually mine?

All those problems make it hard to be 100% sure when exchanging information, that the party we are exchanging information with, is actually the party and not some malicious actor pretending to be the party.

DID to the rescue

The design of DIDs, which is a new form of unique identifier that has been standardized by the W3C, can now help us address these problems of current identifiers, by being:

Decentralized

• The DIDs no longer depend on centralized registries, identity providers, authorities, etc.

Persistent

• Once created, the did is permanently assigned to the subject.

Resolvable

• It is possible to find a basic set of information when resolving the did. Typically, this will lead to a DID Document.

Cryptographically verifiable

• There is a mechanism to cryptographically prove identity and ownership via information provided by the DID Document.

DID format:

The DID is a simple text string built up of three parts:

A variety of “DID methods'', which are different implementations of the DID specification, exist. Considering that DID methods differ in terms of how they are created, registered and resolved, different methods come with different advantages and disadvantages.

For example, while DIDs are often anchored on Registries, such as EBSI (did:ebsi) or the Domain Name Service (did:web), new methods emerged that do not require Registries because their distribution is based on peer-to-peer interactions (e.g. did:key).

Now we can take any did, look at the method and resolve it based on the framework around the method. The resolved content will most of the time be JSON or JSON-LD, although other data formats might also be added in the future. The resolved content is called DID Document.

DID Document

A container of information holding:

The Subject

• The owner of the DID Document

The Controllers

• The entities allowed to introduce changes to the DID Document. The controller may or may not be identical to the "subject". For example, if the DID Document belonged to a DID of a book. The controller would be the author or another related person, rather than the book itself.

Cryptographic data

• The DID document contains the public keys of the corresponding entity. The keys might be of any algorithm (typically elliptical curve keys or RSA keys are used), and are mostly encoded in the JWK format. However, other encoding formats such as PEM or Multibase are also supported. The keys can be classified to be used in certain use cases such as: authentication, verification, etc.

Service endpoints

• Services that the subject wants to mention

DID general flow

Example (did:ebsi)

The identifier did:ebsi:2A9RkiYZJsBHT1nSB3HZAwYMNfgM7Psveyodxrr8KgFvGD5y of the method ebsi would resolve to the following DID document:

{
    "@context": [
        "https://w3id.org/did/v1"
    ],
    // keys used for the authentication of the contoller
    "authentication": [
        "did:ebsi:2A9RkiYZJsBHT1nSB3HZAwYMNfgM7Psveyodxrr8KgFvGD5y#1a7514b2d58141c3982021a6323b99bf"
    ],
    // the subject
    "id": "did:ebsi:2A9RkiYZJsBHT1nSB3HZAwYMNfgM7Psveyodxrr8KgFvGD5y",
    // the cryptographic data used for authentication, verification or other use cases
    // utilizing public keys
    "verificationMethod": [{
        "controller": "did:ebsi:2A9RkiYZJsBHT1nSB3HZAwYMNfgM7Psveyodxrr8KgFvGD5y",
        "id": "did:ebsi:2A9RkiYZJsBHT1nSB3HZAwYMNfgM7Psveyodxrr8KgFvGD5y#1a7514b2d58141c3982021a6323b99bf",
        "publicKeyJwk": {
            "alg": "EdDSA",
            "crv": "Ed25519",
            "kid": "1a7514b2d58141c3982021a6323b99bf",
            "kty": "OKP",
            "use": "sig",
            "x": "tqJADByHRU3YxswewQD4wQYXU9tB43j3PfjofsYEvqs"
        },
        "type": "Ed25519VerificationKey2018"
    }]
}

Welcome to our Introduction to Self-Sovereign Identity (SSI) for developers and technical readers.

Before you get started, feel free to explore other (less technical) resources that will help you and your team to get a more holistic understanding of SSI and digital identity in general:

Understanding SSI requires the understanding of a few core concepts:

• Cryptographic keys, which convey control over digital identities and enable core functionality such as encryption and authentication.

• Wallets, which store our keys (control) and VCs (identity data) and enable the management and sharing of our digital identities and data via easy-to-use applications.

The SSI tech stack:

How the SSI works:

The following graphic shows how SSI works and highlights the core concepts (in blue)

Building Blocks:

Think of these core concepts as different building blocks that are available in different variations and can be put together in different ways:

As a result, there are different “flavours” of SSI depending on which variations of which building blocks have been used and how they have been put together.

Importantly, the differences in terms of technologies that are being used illustrate why interoperability has always been one of the most important topics within the industry and why the development and use of open standards (e.g. by the W3C, Decentralized Identity Foundation, OpenID Foundation and others) are vital for technology and vendor selection.

What is SSI?

Self-Sovereign Identity (SSI) is a user-centric approach to digital identity that gives people and organizations full control over their data. As a result, SSI enables anyone to easily share their data and reliably prove their identity (i.e. who they are and anything about them) without sacrificing security or privacy.

In other words, SSI enables you to “bring your own identity” and this is true for potentially any type of information - from your core identity (e.g. name, age, address) to your education and work records, your health and insurance data, bank account and financial information, etc.

Moreover, SSI can be used to model the digital identities of people, organizations and things.

At the end of the day, SSI promises a digital world in which interactions are effortless and worry-free. It is simply the next evolutionary step in identity management, a new paradigm in which our digital identities are no longer fragmented and locked into silos that are under someone else’s control, but only at our own disposal to be shared securely and privately.

How does SSI work?

SSI allows us to model digital identity just like we are used to the way identity works in the non-digital world based on paper documents and cards. There are just some minor twists.

For example, instead of our identity documents being made of paper or plastic, they are digital credentials made of bits and bytes and instead of storing them in wallets made of leather, they are stored in digital wallets on our phones. Importantly, these digital credentials can be reliably verified by anyone they are shared with online or offline.

In doing so, SSI enables decentralized ecosystems in which different parties can exchange and verify identity-related information. These ecosystems look like three-sided marketplaces, so that every party can take on three roles:

• Issuers - Parties who “issue” identity-related data to people or organizations (“Holders”) in the form of digital credentials. They are the original data sources of an SSI ecosystem. For example, a government issues digital passports to citizens or a university issues digital diplomas to graduates.

• Holders - Individuals or organizations who receive digital credentials that contain data about themselves from various sources (“Issuers”). By aggregating and storing such credentials in digital wallets, Holders can build holistic digital identities that are under their control and can easily be shared with third parties ("Verifiers").

• Verifiers - Parties who rely on data to provide products and services can reliably verify and process data that has been provided by others (“Holders”). Verifiers, also called “Relying Parties”, are usually organizations or individuals in their professional capacity.

Usually, a single party plays only one of these roles per interaction. However, it is perfectly normal for a party to take on different roles in different interactions.

For example:

• A university (Holder) is being accredited to issue certain types of educational credentials by a national authority (Issuer).

• A university (Issuer) issues a digital diploma to a graduate (Holder), who can share this information with a recruiter (Verifier) in the course of a job application.

• After the recruiting process, a recruiter (Issuer) issues the results of an applicant’s assessment (e.g. skills, referral) to the applicant (Holder), who can share this information with a new manager or another recruiter (Verifier).

• A manager (Issuer) issues the results of a performance review to his employee (Holder) who can share this information with HR (e.g. to improve talent development programs).

Registries serve as a single source of truth which all participants of an SSI ecosystem can trust. Depending on the ecosystem, registries make information accessible to anyone or just a limited group. Registries are important because they enable:

• (Distributed) Public Key Infrastructures (DPKIs) which establishes an open distribution system for public keys which can be used for encryption and authentication among others.

• Trust Registries hold reliable information about people, organizations, things and even credentials (e.g. data models, status and validity information) to ensure that different parties can trust each other and the identity-related data they exchange.

Different technologies can be used to implement Registries. For example:

• Blockchains or L1: Typically blockchains are used because it is unfeasible (or even impossible) to tamper with them. The fact that no single organization can change the contents of a blockchain or manipulate the terms by which it is governed are very aligned with the requirements for identity ecosystems. Today, we see a growing number of developers and organizations focusing on so-called permissioned blockchains (i.e. only a selected group can “write”) like Ethereum Quorum/Enterprise. Permissionless blockchains, like Ethereum, are still used, but less than the permissioned alternatives for a variety of reasons like scalability, costs, lack of customisable governance frameworks.

• L2: Layer two networks sit on top of blockchains and aggregate data before anchoring it. The main idea behind them is to circumvent common challenges of public, permissionless blockchains like scalability and cost issues. The most popular implementations in the context of identity are “ION” (for Bitcoin) and “Element” (for Ethereum).

• Other Distributed Ledger Technologies (DLTs): Sometimes other DLTs are utilised like the Interplanetary File System (IPFS) though its use for digital identity remains limited.

• Domain Name Service (DNS): Considering certain drawbacks of DLTs and their relatively slow adoption by the mass market, DNS can also be used to serve as a registry. Though it is not fully decentralised (considering its underlying governance framework), DNS has many advantages like its maturity and global adoption.

Importantly, SSI can be implemented without registries, particularly without blockchains, because identity data (or at least personal data of individuals) is never anchored due to privacy and compliance reasons. However, by combining SSI with blockchains (or other technologies), robust and trustworthy identity ecosystems that utilise transparent DPKIs and reliable Trust Registries can emerge.

The SSI-Kit's functionality can be used in a variety of ways. Select your preference to get started

Tutorials

• My First Verifiable Credential (VC) - Issue and verify your first VC using the SSI-Kit Api

• Advanced Verifiable Credentials (VC) - Leverage custom credential templates, the credential status property, prebuild and custom verification policies.

Before we dive deeper into Verifiable Credentials and learn about their structure and how they work, we will have a look at the problems of today's credentials.

Credentials today

Today's credentials are easy to fake, hard to verify, and not privacy preserving by design. Making it hard for business and people offline but especially online to trust each other, when exchanging information and data. This brings about many problems, thereunder:

• To verify that a document or claim presented is actually valid, can take up many resources and time. Just think about, what you had to do last time you opened up a bank account. The presenting of your ID card via a video call, taking selfies etc.

• Often the credentials provided by you to get access to a service, are then stored on centralized servers. This makes them not only vulnerable to data breaches, but you also need to trust the organization that they only use the data in ways you would agree with.

• You might be forced to disclose more information than needed. The police officer checking your driver license, in most cases, only needs to know that you are allowed to drive, but not where you live or your name.

• Organizations employing people who claim to have a skill by presenting a fake certificate, can get jobs, which, when performed poorly, could have catastrophic consequences.

This is why we need a better way to verify the claims presented, and that is where Verifiable Credentials come in.

Verifiable Credentials to the Rescue

• Easy to verify: There is a clearly defined and reliable way of verifying a Verifiable Credential.

• Temper-proof: No one expect the issuer (entity creating the VC) can change the claims stated in the VC.

• Independent: No need to contact the issuer of the presented certificate to be certain about its validity. The check can happen in an independent, asynchronous way.

• Data is owned: The holder of a certificate now owns the data and decides what to share and when, only providing proof but never actually giving it (a copy) to the service provider.

• Portable: The user is free to choose where to take their VC and in which wallet it is saved.

The lifecycle of a Verifiable Credential

Setup

• Holder setup: The holder generates the DID via the wallet and saves the private and public key as part of the DID Document, to be able to request, receive and present Verifiable Credentials from thereon. The DID and the DID Document will never be put into any registry, it will only exist locally in the wallet.

• Verifier setup: The verifier only needs to have the technology to communicate with the registries when presented with a VC, to validate its authenticity using the DID and the DID Document from the issuer.

After the registration of the issuer and the setup of the wallet for the holder, the holder can now receive a VC from the issuer.

Issuance & Content

When the holder receives their Verifiable Credential it will be saved on their wallet, and it will contain the following:

• Metadata:

  • The DID of the issuer

  • The status of the credential (expiration and issuing date, revoke state)

• Claims:

  • The DID of the holder of the credential

  • The claims about the subject (what the issuer asserts about the subject). This could be, if they can drive a car and what type of car (driver license) or the subject of their study and knowledge areas skilled in (university certificate).

• Proof:

  • This will contain the signatures of the issuer, which can be used to see if the content of the VC has been tempered with and for an authenticity check.

Using the Certificate

2. Validate that the DID of the holder, stated in the certificate, is the person presenting the VC.

3. Checking if all the state values are valid (expiration date and if the certificate is revoked or not).

4. Checking the claims about the subject and if they match the requirements to give the person access to the service they are requesting to get access to.

5. Checking the signatures of the issuer and the holder, by getting the DID of the issuer from the registry and the DID from the holder in their wallet and validating it using the public keys presented in the related DID documents.

When all the checks pass, the verifier can now grant the holder access to the service requested.

Example of a Verifiable Credential

Why do we need Verifiable Presentations?

How Verifiable Presentations are composed?

Verifiable Presentations represent a composition of claims, which can come from one or multiple Verifiable Credentials, of which the authorship is verified. This gives the holder of credentials the chance of composing context specify presentations, which only contain the data which is relevant in that context. When presenting the composition to a verifier, it can easily be validated.

Taking a closer look at how they are built up. We will see four different layers:

1. Presentation Layer - Being the Verifiable Presentation itself with the required metadata

2. Credential Layer - Referenced by Layer 1 and pointing to one or more credentials

3. Credential Proof Layer - Holding the proofs of the credentials and the signatures from Layer

4. Presentation Proof Layer - Holding the proof of the Verifiable Presentation and its signatures

Example of a Verifiable Presentation in code

Swagger | Redoc

The Signatory API exposes the "issuance" endpoint, which provides flexible integration possibilities for anyone intending to act as an "Issuer" (i.e. create, sign and issue Verifiable Credentials), as follows:

• Credentials - issue credentials

• Templates - create and mange credential templates

• Revocations - revocation related functions

Credentials

If you're new to VCs, check out the intro section for an overview.

The /v1/credentials/issue endpoint issues a specified credential.

curl -X 'POST' \
  'https://signatory.ssikit.walt.id/v1/credentials/issue' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '<request-body>'

{
    "templateId": "string",
    "config":
    {
        "issuerDid": "string",
        "subjectDid": "string",
        "verifierDid": "string",
        "issuerVerificationMethod": "string",
        "proofType": "JWT",
        "domain": "string",
        "nonce": "string",
        "proofPurpose": "string",
        "credentialId": "string",
        "issueDate": "2022-10-06T18:09:14.570Z",
        "validDate": "2022-10-06T18:09:14.570Z",
        "expirationDate": "2022-10-06T18:09:14.570Z",
        "dataProviderIdentifier": "string",
        "ldSignatureType": "string",
        "creator": "string",
        "ecosystem": "string",
        "statusType": "string"
    },
    "credentialData":
    {
        "additionalProp1":
        {},
        "additionalProp2":
        {},
        "additionalProp3":
        {}
    }
}

The issued credential displayed either in JSON-LD or JWT format

E.g. Issue a UniversityDegree credential in the default JSON-LD format. In case you don't have the DID for the Issuer and or the Holder, you can create one here.

curl -X 'POST' \
  'https://signatory.ssikit.walt.id/v1/credentials/issue' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "templateId": "UniversityDegree",
    "config":
    {
        "issuerDid": "did:web:walt.id",
        "subjectDid": "did:web:my.domain"
    },
    "credentialData":
    {
        "credentialSubject":
        {
            "degree":
            {
                "name": "Bachelor of Science and Arts",
                "type": "BachelorDegree"
            }
        }
    }
}'

{
    "templateId": "UniversityDegree",
    "config":
    {
        "issuerDid": "did:web:walt.id",
        "subjectDid": "did:web:my.domain"
    },
    "credentialData":
    {
        "credentialSubject":
        {
            "degree":
            {
                "name": "Bachelor of Science and Arts",
                "type": "BachelorDegree"
            }
        }
    }
}

{
    "@context":
    [
        "https://www.w3.org/2018/credentials/v1",
        "https://www.w3.org/2018/credentials/examples/v1"
    ],
    "credentialSubject":
    {
        "degree":
        {
            "name": "Bachelor of Science and Arts",
            "type": "BachelorDegree"
        },
        "id": "did:web:my.domain"
    },
    "id": "urn:uuid:d36986f1-3cc0-4156-b5a4-6d3deab84270",
    "issued": "2022-10-07T09:53:41.369913097Z",
    "issuer":
    {
        "id": "did:web:walt.id"
    },
    "validFrom": "2022-10-07T09:53:41.369917079Z",
    "issuanceDate": "2022-10-07T09:53:41.369917079Z",
    "type":
    [
        "VerifiableCredential",
        "UniversityDegreeCredential"
    ],
    "proof":
    {
        "type": "Ed25519Signature2018",
        "creator": "did:web:walt.id",
        "created": "2022-10-07T09:53:41Z",
        "domain": "https://api.preprod.ebsi.eu",
        "nonce": "dc2be572-cca4-43dc-9903-0fec1dcf786f",
        "jws": "eyJiNjQiOmZhbHNlLCJjcml0IjpbImI2NCJdLCJhbGciOiJFZERTQSJ9..7EYkgjNRJ_hh0F5kONnPfrC4PLvg1g82czeANllDngsbk36a8lnHSlwersSqY0tdER4xIe7vbNVzi39C2DZTDQ"
    }
}

Check out the Issue with status section to learn about how to issue a verifiable credential with a credentialStatus property.

Templates

The currently available template functions are:

• list - display the list of Templates

• import - import a custom template

• load - display the content of the template having the specified id

List templates

The /v1/templates endpoint returns the list of the available template ids

curl -X 'GET' \
  'https://signatory.ssikit.walt.id/v1/templates' \
  -H 'accept: application/json'

[
    "string"
]

E.g. List the templates

curl -X 'GET' \
  'https://signatory.ssikit.walt.id/v1/templates' \
  -H 'accept: application/json'

[
    "DataSelfDescription",
    "VerifiableDiploma",
    "VerifiableVaccinationCertificate",
    "LegalPerson",
    "VerifiableAuthorization",
    "Europass",
    "KybMonoCredential",
    "KycCredential",
    "VerifiableMandate",
    "VerifiablePresentation",
    "EuropeanBankIdentity",
    "KybCredential",
    "VerifiableAttestation",
    "OpenBadgeCredential",
    "PeerReview",
    "DataConsortium",
    "ProofOfResidence",
    "AmletCredential",
    "ParticipantCredential",
    "PermanentResidentCard",
    "UniversityDegree",
    "VerifiableId",
    "DataServiceOffering",
    "GaiaxCredential",
    "Iso27001Certificate"
]

Import template

The /v1/templates/{id} endpoint to import your custom credential template

• id path parameter (required) - id of the template, e.g. MyCustomCredential

curl -X 'POST' \
  'https://signatory.ssikit.walt.id/v1/templates/{id}' \
  -H 'accept: application/json'
  -H 'Content-Type: application/json' \
  -d '<request-body>'

{
  "type": [
    "VerifiableCredential",
    "MyCustomCredential"
  ],
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://www.w3.org/2018/credentials/examples/v1"
  ],
  "id": "string",
  "issuer": {
    "id": "string"
  },
  "issued": "2020-03-10T04:24:12.164Z",
  ... // custom data in json
}

{
  "type": [
    "VerifiableCredential",
    "MyCustomCredential"
  ],
  "@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"
  },
  "issued": "2020-03-10T04:24:12.164Z",
  "credentialSubject": {
    "id": "did:example:123",
    "firstName": "",
    "lastName": "",
    "country": "Austria"
  }
}

null

Load template

The /v1/templates/{id} endpoint displays the content of the template having the parameters:

• id path parameter (required) - id of the template

curl -X 'GET' \
  'https://signatory.ssikit.walt.id/v1/templates/{id}' \
  -H 'accept: application/json'

The template content as JSON

E.g. Load the template for the id set to UniversityDegree.

curl -X 'GET' \
  'https://signatory.ssikit.walt.id/v1/templates/UniversityDegree' \
  -H 'accept: application/json'

{
    "@context":
    [
        "https://www.w3.org/2018/credentials/v1",
        "https://www.w3.org/2018/credentials/examples/v1"
    ],
    "credentialSubject":
    {
        "degree":
        {
            "name": "Bachelor of Science and Arts",
            "type": "BachelorDegree"
        },
        "id": "did:example:123"
    },
    "id": "http://example.gov/credentials/3732",
    "issued": "2020-03-10T04:24:12.164Z",
    "issuer":
    {
        "id": "did:example:456"
    },
    "type":
    [
        "VerifiableCredential",
        "UniversityDegreeCredential"
    ]
}

Revocations

Refer to Credential Statuses section for more details on verifiable credential revocations.

Manage keys, DIDs, issue Verifiable Credentials, and verify them using the SSI-Kit's REST API.

Installation & Running the Project

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

After successfully running the project, you will have the endpoints, described below, available for use.

Exposed endpoints:

Next Steps

Tutorials

The Auditor API enables anybody to act as a "Verifier" (i.e. verify Verifiable Credentials or Verifiable Presentations). The validation steps can be easily configured by existing or custom policies.

The following functionality is available:

Verification

The /v1/verify endpoint verifies a list of credentials / presentations specified in the JSON-LD format against a set of policies. Each of the policy should be registered with the Auditor before being used in the verification. If at least one of the listed policies fails the verification, then the entire credential is considered to be invalid.

E.g Verification of a UniversityDegree credential against Signature and JsonSchema policies, where SignaturePolicy is failing.

Policies

The Auditor Rest API also enables policy management with the following methods:

List policies

The /v1/policies endpoint lists the available verification policies. The policy id field is used to reference the policy during verification.

E.g. Listing of the verification policies

Create policy

The /v1/create/{name} creates a dynamic policy. The following parameters can be specified:

• name path parameter (required) - specifies the value to be used as the policy id

• update query parameter (optional, defualts to false) - accepts boolean values and specifies whether it should override an existing policy with the same name (only if the policy is mutable)

• downloadPolicy query parameter (optional, defaults to false) - accepts boolean values and identifies the scope of the policy field:

  • specifies a remote source that should be resolved to a policy

  • specifies the actual policy content

E.g. Creating a Rego policy that checks if a credential subject id is not null or empty

Delete policy

The /v1/delete/{name} endpoint deletes a dynamic policy. The following parameters can be specified:

• name path parameter (required) - specifies the id value of the policy

E.g. Removing the policy having 'MyPolicy' name

The Custodian API provides management functions for maintaining secrets and sensitive data (e.g. keys, Verifiable Credentials) in a secure way:

The following key management functions are available:

• list - list of key ids

• load - load the public key in JWK format

• delete - delete key

• generate - generate key

• import - import key

• export - export key

List key ids

The /v1/key endpoint lists the available key ids.

curl -X 'GET' \
  'https://core.ssikit.walt.id/v1/key' \
  -H 'accept: application/json'

No parameters

The list of key ids

E.g. List the available key ids.

curl -X 'GET' \
  'https://core.ssikit.walt.id/v1/key' \
  -H 'accept: application/json'

[
    "e548f032cadf4145ab6886a57c2e87e6",
    "e70e8fd8932043caa7c857c3b944d0e0",
    "b50db0c1f73242b8bb0f2f6324e15ec3",
    "did:key:z6MkkLmAVeM3P6B2LJ2xGrK1wVojCoephK4G9VrCcct42ADX#z6MkkLmAVeM3P6B2LJ2xGrK1wVojCoephK4G9VrCcct42ADX",
    "8cc0b1707ea345ed83e479469d42aac2",
    "c5b11445be0e4d37863170df3328630b",
    "8394ea7883bc4328a3f18b146b7e16bd",
    "fd36a0159592413da1d89f192dd77dcd",
    "did:key:z6Mkm8NbvDnnxJ2t5zLGSkYGCWZiqq11Axr58xQ3ZG1Jss3z#z6Mkm8NbvDnnxJ2t5zLGSkYGCWZiqq11Axr58xQ3ZG1Jss3z",
    "fa9296808e64440d89e6d245a1709141",
    "8dd54d6ae25a4818b1497530a8659dc1"
]

Load key

The /v1/key/{id} endpoint loads the public component of the provided key id in JWK format:

• id - path parameter (required) - the key id

curl -X 'GET' \
  'https://core.ssikit.walt.id/v1/key/{id}' \
  -H 'accept: application/json'

No parameters

The string for the public component of the key

E.g. Load the key having id = e548f032cadf4145ab6886a57c2e87e6.

curl -X 'GET' \
  'https://core.ssikit.walt.id/v1/key/e548f032cadf4145ab6886a57c2e87e6' \
  -H 'accept: application/json'

"{\"kty\":\"OKP\",\"use\":\"sig\",\"crv\":\"Ed25519\",\"kid\":\"e548f032cadf4145ab6886a57c2e87e6\",\"x\":\"jT8YleOQnaABpZTnvId3WoID4Pia9Lex9OndqQ22Xxs\",\"alg\":\"EdDSA\"}"

Delete key

The /v1/key/{id} endpoint deletes the specified key.

curl -X 'DELETE' \
  'https://core.ssikit.walt.id/v1/key/' \
  -H 'accept: application/json' \
  -H 'Content-Type: text/plain' \
  -d '<request-body>'

The key id string

Code 200

E.g. Delete the key having id = e548f032cadf4145ab6886a57c2e87e6.

curl -X 'DELETE' \
  'https://core.ssikit.walt.id/v1/key/' \
  -H 'accept: application/json' \
  -H 'Content-Type: text/plain' \
  -d 'e548f032cadf4145ab6886a57c2e87e6'

e548f032cadf4145ab6886a57c2e87e6

Generate key

The /v1/key/gen generates a new key using the specified algorithm.

curl -X 'POST' \
  'https://core.ssikit.walt.id/v1/key/gen' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '<request-body>'

{
    "keyAlgorithm": "EdDSA_Ed25519"
}

{
    "id": "string"
}

E.g. Generate a new key using the EdDSA_Ed25519 algorithm.

curl -X 'POST' \
  'https://core.ssikit.walt.id/v1/key/gen' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "keyAlgorithm": "EdDSA_Ed25519"
}'

{
    "keyAlgorithm": "EdDSA_Ed25519"
}

{
    "id": "2251db0d15eb4e96b80c471edbaed185"
}

Import key

The /v1/key/import endpoint imports a key (JWK or PEM format) to the underlying keystore.

curl -X 'POST' \
  'https://core.ssikit.walt.id/v1/key/import' \
  -H 'accept: application/json' \
  -H 'Content-Type: text/plain' \
  -d '<request-body>'

The key string in JWK or PEM format

{
    "id": "string"
}

E.g. Import a public key specified in JWK format.

curl -X 'POST' \
  'https://core.ssikit.walt.id/v1/key/import' \
  -H 'accept: application/json' \
  -H 'Content-Type: text/plain' \
  -d '{"kty":"OKP","use":"sig","crv":"Ed25519","kid":"bc6fa6b0593648238c4616800bed7746","x":"YyswAyRO2Aur8Jmzc8aOvI3AWFka3ZynJwB84a0FJVU","alg":"EdDSA"}'

{
    "kty": "OKP",
    "use": "sig",
    "crv": "Ed25519",
    "kid": "bc6fa6b0593648238c4616800bed7746",
    "x": "YyswAyRO2Aur8Jmzc8aOvI3AWFka3ZynJwB84a0FJVU",
    "alg": "EdDSA"
}

{
    "id": "bc6fa6b0593648238c4616800bed7746"
}

Export key

The /v1/key/export endpoint exports public and private key part (if supported by underlying keystore).

curl -X 'POST' \
  'https://core.ssikit.walt.id/v1/key/export' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '<request-body>'

{
    "keyAlias": "string",
    "format": "JWK",
    "exportPrivate": true
}

The key in the specified format, JWK or PEM

E.g. Export the public key with id = bc6fa6b0593648238c4616800bed7746 as JWK.

curl -X 'POST' \
  'https://core.ssikit.walt.id/v1/key/export' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "keyAlias": "bc6fa6b0593648238c4616800bed7746",
  "format": "JWK",
  "exportPrivate": false
}'

{
    "keyAlias": "bc6fa6b0593648238c4616800bed7746",
    "format": "JWK",
    "exportPrivate": false
}

{
    "kty": "OKP",
    "use": "sig",
    "crv": "Ed25519",
    "kid": "bc6fa6b0593648238c4616800bed7746",
    "x": "YyswAyRO2Aur8Jmzc8aOvI3AWFka3ZynJwB84a0FJVU",
    "alg": "EdDSA"
}

Key management functions include:

• List - lists the available keys

• Load - loads a key specified by its alias

• Generate - generate a key using the specified algorithm

• Import - imports a key

• Delete - deletes a specific key

• Export - exports public and private key parts (if supported by the underlying keystore)

List keys

The /keys endpoint lists the key available to the Custodian

curl -X 'GET' \
  'https://custodian.ssikit.walt.id/keys' \
  -H 'accept: application/json'

No parameters

{
    "list":
    [
        {
            "algorithm": "string",
            "cryptoProvider": "string",
            "keyId":
            {
                "id": "string"
            },
            "keyPair": {},
            "keysetHandle": null
        }
    ]
}

E.g. List the available keys

curl -X 'GET' \
  'https://custodian.ssikit.walt.id/keys' \
  -H 'accept: application/json'

{
    "list":
    [
        {
            "algorithm": "EdDSA_Ed25519",
            "cryptoProvider": "SUN",
            "keyId":
            {
                "id": "e548f032cadf4145ab6886a57c2e87e6"
            },
            "keyPair": {},
            "keysetHandle": null
        },
        {
            "algorithm": "EdDSA_Ed25519",
            "cryptoProvider": "SUN",
            "keyId":
            {
                "id": "e70e8fd8932043caa7c857c3b944d0e0"
            },
            "keyPair": {},
            "keysetHandle": null
        },
        {
            "algorithm": "EdDSA_Ed25519",
            "cryptoProvider": "SUN",
            "keyId":
            {
                "id": "b50db0c1f73242b8bb0f2f6324e15ec3"
            },
            "keyPair": {},
            "keysetHandle": null
        },
        {
            "algorithm": "EdDSA_Ed25519",
            "cryptoProvider": "SUN",
            "keyId":
            {
                "id": "did:key:z6MkkLmAVeM3P6B2LJ2xGrK1wVojCoephK4G9VrCcct42ADX#z6MkkLmAVeM3P6B2LJ2xGrK1wVojCoephK4G9VrCcct42ADX"
            },
            "keyPair": {},
            "keysetHandle": null
        },
        {
            "algorithm": "EdDSA_Ed25519",
            "cryptoProvider": "SUN",
            "keyId":
            {
                "id": "8cc0b1707ea345ed83e479469d42aac2"
            },
            "keyPair": {},
            "keysetHandle": null
        },
        {
            "algorithm": "EdDSA_Ed25519",
            "cryptoProvider": "SUN",
            "keyId":
            {
                "id": "did:key:z6Mkv58vGsBMwbiyQ3P93MRnYfRgGvn4STEEsj5hFHYe51wu#z6Mkv58vGsBMwbiyQ3P93MRnYfRgGvn4STEEsj5hFHYe51wu"
            },
            "keyPair": {},
            "keysetHandle": null
        },
        {
            "algorithm": "EdDSA_Ed25519",
            "cryptoProvider": "SUN",
            "keyId":
            {
                "id": "186a1e0a6d42459ba902724fe7643ed4"
            },
            "keyPair": {},
            "keysetHandle": null
        },
        {
            "algorithm": "EdDSA_Ed25519",
            "cryptoProvider": "SUN",
            "keyId":
            {
                "id": "c5b11445be0e4d37863170df3328630b"
            },
            "keyPair": {},
            "keysetHandle": null
        }
    ]
}

Load key

The /keys/{alias} endpoint loads a key specified by its alias.

curl -X 'GET' \
  'https://custodian.ssikit.walt.id/keys/{alias}' \
  -H 'accept: application/json'

No parameters

{
    "algorithm": "string",
    "cryptoProvider": "string",
    "keyId":
    {
        "id": "string"
    },
    "keyPair": {},
    "keysetHandle": null
}

E.g. Load a key with id e548f032cadf4145ab6886a57c2e87e6

curl -X 'GET' \
  'https://custodian.ssikit.walt.id/keys/e548f032cadf4145ab6886a57c2e87e6' \
  -H 'accept: application/json'

{
    "algorithm": "EdDSA_Ed25519",
    "cryptoProvider": "SUN",
    "keyId":
    {
        "id": "e548f032cadf4145ab6886a57c2e87e6"
    },
    "keyPair": {},
    "keysetHandle": null
}

Generate key

The /keys/generate endpoint generates a key using the specified algorithm.

curl -X 'POST' \
  'https://custodian.ssikit.walt.id/keys/generate' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '<request-body>'

{
    "keyAlgorithm": "EdDSA_Ed25519"
}

{
    "algorithm": "string",
    "cryptoProvider": "string",
    "keyId":
    {
        "id": "string"
    },
    "keyPair": {},
    "keysetHandle": null
}

E.g. Generate a key using the EdDSA_Ed25519 algorithm.

curl -X 'POST' \
  'https://custodian.ssikit.walt.id/keys/generate' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{ "keyAlgorithm": "EdDSA_Ed25519" }'

{
    "keyAlgorithm": "EdDSA_Ed25519"
}

{
    "algorithm": "EdDSA_Ed25519",
    "cryptoProvider": "SUN",
    "keyId":
    {
        "id": "8394ea7883bc4328a3f18b146b7e16bd"
    },
    "keyPair": {},
    "keysetHandle": null
}

Import key

The /keys/import endpoint imports a key (JWK or PEM format) to the underlying keystore.

curl -X 'POST' \
  'https://custodian.ssikit.walt.id/keys/import' \
  -H 'accept: application/json' \
  -H 'Content-Type: text/plain' \
  -d '<request-body>'

{
    "id": "string"
}

E.g. Import a public key specified in JWK format.

curl -X 'POST' \
  'https://custodian.ssikit.walt.id/keys/import' \
  -H 'accept: application/json' \
  -H 'Content-Type: text/plain' \
  -d '{"kty":"OKP","use":"sig","crv":"Ed25519","kid":"bc6fa6b0593648238c4616800bed7746","x":"YyswAyRO2Aur8Jmzc8aOvI3AWFka3ZynJwB84a0FJVU","alg":"EdDSA"}'

{
    "kty": "OKP",
    "use": "sig",
    "crv": "Ed25519",
    "kid": "bc6fa6b0593648238c4616800bed7746",
    "x": "YyswAyRO2Aur8Jmzc8aOvI3AWFka3ZynJwB84a0FJVU",
    "alg": "EdDSA"
}

{
    "id": "bc6fa6b0593648238c4616800bed7746"
}

Delete key

The /keys/{id} deletes the specified as parameter:

• id path parameter (required) - the key alias

curl -X 'DELETE' \
  'https://custodian.ssikit.walt.id/keys/{id}' \
  -H 'accept: application/json'

No parameters

Code 200

E.g. Delete the key with id bc6fa6b0593648238c4616800bed7746

curl -X 'DELETE' \
  'https://custodian.ssikit.walt.id/keys/bc6fa6b0593648238c4616800bed7746' \
  -H 'accept: application/json'

Export key

The /keys/export endpoint exports a key.

curl -X 'POST' \
  'https://custodian.ssikit.walt.id/keys/export' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '<request-body>'

{
    "keyAlias": "string",
    "format": "JWK",
    "exportPrivate": true
}

The key in the specified format, JWK or PEM

E.g. Export the public key with id = e548f032cadf4145ab6886a57c2e87e6 as JWK.

curl -X 'POST' \
  'https://custodian.ssikit.walt.id/keys/export' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "keyAlias": "e548f032cadf4145ab6886a57c2e87e6",
  "format": "JWK",
  "exportPrivate": false
}'

{
    "keyAlias": "e548f032cadf4145ab6886a57c2e87e6",
    "format": "JWK",
    "exportPrivate": false
}

{
    "kty": "OKP",
    "use": "sig",
    "crv": "Ed25519",
    "kid": "e548f032cadf4145ab6886a57c2e87e6",
    "x": "jT8YleOQnaABpZTnvId3WoID4Pia9Lex9OndqQ22Xxs",
    "alg": "EdDSA"
}

DID management functions enable the following:

• List - lists the available DIDs

• Load - loads a DID by the specified id

• Delete - deletes a DID by the specified url

• Create - creates a new DID

• Resolve - resolves a DID to a document

• Import - import a DID

For more info on DIDs, go here.

List DID

The /did endpoint lists the available DIDs.

curl -X 'GET' \
  'https://custodian.ssikit.walt.id/did' \
  -H 'accept: application/json'

No parameters

The list of DID strings

E.g. List the available DIDs

curl -X 'GET' \
  'https://custodian.ssikit.walt.id/did' \
  -H 'accept: application/json'

[
    "did:key:z6MkkLmAVeM3P6B2LJ2xGrK1wVojCoephK4G9VrCcct42ADX",
    "did:web:my.domain",
    "did:web:walt.id",
    "did:key:z6Mkv58vGsBMwbiyQ3P93MRnYfRgGvn4STEEsj5hFHYe51wu"
]

Load DID

The /did/{id} endpoint loads a DID specified by:

• id path parameter (required) - the DID url string

curl -X 'GET' \
  'https://custodian.ssikit.walt.id/{id}' \
  -H 'accept: application/json'

No parameters

{
    "assertionMethod":
    [
        "string"
    ],
    "authentication":
    [
        "string"
    ],
    "@context":
    [
        "string"
    ],
    "id": "string",
    "verificationMethod":
    [
        {
            "controller": "string",
            "id": "string",
            "publicKeyJwk":
            {
                "alg": "string",
                "crv": "string",
                "kid": "string",
                "kty": "string",
                "use": "string",
                "x": "string"
            },
            "type": "string"
        }
    ]
}

E.g Load the DID having the id = did:web:walt.id.

curl -X 'GET' \
  'https://custodian.ssikit.walt.id/did/did%3Aweb%3Awalt.id' \
  -H 'accept: application/json'

{
    "assertionMethod":
    [
        "did:web:walt.id#186a1e0a6d42459ba902724fe7643ed4"
    ],
    "authentication":
    [
        "did:web:walt.id#186a1e0a6d42459ba902724fe7643ed4"
    ],
    "@context":
    [
        "https://www.w3.org/ns/did/v1"
    ],
    "id": "did:web:walt.id",
    "verificationMethod":
    [
        {
            "controller": "did:web:walt.id",
            "id": "did:web:walt.id#186a1e0a6d42459ba902724fe7643ed4",
            "publicKeyJwk":
            {
                "alg": "EdDSA",
                "crv": "Ed25519",
                "kid": "186a1e0a6d42459ba902724fe7643ed4",
                "kty": "OKP",
                "use": "sig",
                "x": "7-ofBq4vt0ePzC5IjiWkqTedfSv7WJJr6-HsQNXsr2M"
            },
            "type": "Ed25519VerificationKey2019"
        }
    ]
}

Delete DID

The /did/{id} deletes the DID specified by:

• url - path parameter (required) - the DID url string

curl -X 'DELETE' \
  'https://custodian.ssikit.walt.id/did/{id}' \
  -H 'accept: application/json'

No parameters

Code 200

E.g. Delete the DID having id = did:web:walt.id.

curl -X 'DELETE' \
  'https://custodian.ssikit.walt.id/did/did%3Aweb%3Awalt.id' \
  -H 'accept: application/json'

Create DID

The /did/create endpoint creates a DID.

curl -X 'POST' \
  'https://custodian.ssikit.walt.id/did/create' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '<request-body>'

{
    "method": "string",
    "keyAlias": "string",
    "method-dependent-options": "..."
}

The DID url string

The method and keyAlias properties are common for all did-method requests, method being required, while keyAlias - optional (if not specified, a new key will be automatically created using the default algorithm according to the did-method). The method-dependent options have default values, if not specified otherwise. Below are the available properties by did-method.

{
    "method": "key",
    "keyAlias": "string",
    "useJwkJcsPub": "boolean"
}

{
  "method": "web",
  "keyAlias": "string",
  "didWebDomain": "string",
  "didWebPath": "string"
}

{
    "method": "ebsi",
    "keyAlias": "string",
    "version": "int"
}

{
    "method": "cheqd",
    "keyAlias": "string",
    "network": "string"
}

{
    "method": "iota",
    "keyAlias": "string"
}

{
    "method": "jwk",
    "keyAlias": "string"
}

E.g. Create a DID using the web method having the domain set to walt.id.

curl -X 'POST' \
  'https://custodian.ssikit.walt.id/did/create' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "method": "web",
  "didWebDomain": "walt.id"
}'

{
    "method": "web",
    "didWebDomain": "walt.id"
}

did:web:walt.id

Resolve DID

The /did/resolve endpoint resolves a DID.

curl -X 'POST' \
  'https://custodian.ssikit.walt.id/did/resolve' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '<request-body>'

{
    "did": "string"
}

{
    "assertionMethod":
    [
        "string"
    ],
    "authentication":
    [
        "string"
    ],
    "@context":
    [
        "string"
    ],
    "id": "string",
    "verificationMethod":
    [
        {
            "controller": "string",
            "id": "string",
            "publicKeyJwk":
            {
                "alg": "string",
                "crv": "string",
                "kid": "string",
                "kty": "string",
                "use": "string",
                "x": "string"
            },
            "type": "string"
        }
    ]
}

E.g. Reslove the DID having id = did:key:z6MkkLmAVeM3P6B2LJ2xGrK1wVojCoephK4G9VrCcct42ADX.

curl -X 'POST' \
  'https://custodian.ssikit.walt.id/did/resolve' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "did": "did:key:z6MkkLmAVeM3P6B2LJ2xGrK1wVojCoephK4G9VrCcct42ADX"
}'

{
    "did": "did:key:z6MkkLmAVeM3P6B2LJ2xGrK1wVojCoephK4G9VrCcct42ADX"
}

{
    "assertionMethod":
    [
        "did:key:z6MkkLmAVeM3P6B2LJ2xGrK1wVojCoephK4G9VrCcct42ADX#z6MkkLmAVeM3P6B2LJ2xGrK1wVojCoephK4G9VrCcct42ADX"
    ],
    "authentication":
    [
        "did:key:z6MkkLmAVeM3P6B2LJ2xGrK1wVojCoephK4G9VrCcct42ADX#z6MkkLmAVeM3P6B2LJ2xGrK1wVojCoephK4G9VrCcct42ADX"
    ],
    "capabilityDelegation":
    [
        "did:key:z6MkkLmAVeM3P6B2LJ2xGrK1wVojCoephK4G9VrCcct42ADX#z6MkkLmAVeM3P6B2LJ2xGrK1wVojCoephK4G9VrCcct42ADX"
    ],
    "capabilityInvocation":
    [
        "did:key:z6MkkLmAVeM3P6B2LJ2xGrK1wVojCoephK4G9VrCcct42ADX#z6MkkLmAVeM3P6B2LJ2xGrK1wVojCoephK4G9VrCcct42ADX"
    ],
    "@context":
    [
        "https://www.w3.org/ns/did/v1"
    ],
    "id": "did:key:z6MkkLmAVeM3P6B2LJ2xGrK1wVojCoephK4G9VrCcct42ADX",
    "keyAgreement":
    [
        "did:key:z6MkkLmAVeM3P6B2LJ2xGrK1wVojCoephK4G9VrCcct42ADX#z6LShXhgLqK3vQX3eg18gwZUYNtt6M6FjPqpV1eQD86m8Hwh"
    ],
    "verificationMethod":
    [
        {
            "controller": "did:key:z6MkkLmAVeM3P6B2LJ2xGrK1wVojCoephK4G9VrCcct42ADX",
            "id": "did:key:z6MkkLmAVeM3P6B2LJ2xGrK1wVojCoephK4G9VrCcct42ADX#z6MkkLmAVeM3P6B2LJ2xGrK1wVojCoephK4G9VrCcct42ADX",
            "publicKeyBase58": "6tW7uQ6c3YgZDoCFbHMB6QFjPENyHRouTUwGnLv36wS9",
            "type": "Ed25519VerificationKey2019"
        },
        {
            "controller": "did:key:z6MkkLmAVeM3P6B2LJ2xGrK1wVojCoephK4G9VrCcct42ADX",
            "id": "did:key:z6MkkLmAVeM3P6B2LJ2xGrK1wVojCoephK4G9VrCcct42ADX#z6LShXhgLqK3vQX3eg18gwZUYNtt6M6FjPqpV1eQD86m8Hwh",
            "publicKeyBase58": "6rXWpXWBpwoJZHdNAJ3XDngQFCZ92nffc2viifTEQvAw",
            "type": "X25519KeyAgreementKey2019"
        }
    ]
}

Import DID

The /did/import endpoint resolves and imports the DID to the underlying data store.

curl -X 'POST' \
  'https://custodian.ssikit.walt.id/did/import' \
  -H 'accept: application/json' \
  -H 'Content-Type: text/plain' \
  -d '<request-body>'

Code 201

E.g. Import DID having id = did:key:z6Mkm8NbvDnnxJ2t5zLGSkYGCWZiqq11Axr58xQ3ZG1Jss3z.

curl -X 'POST' \
  'https://custodian.ssikit.walt.id/did/import' \
  -H 'accept: application/json' \
  -H 'Content-Type: text/plain' \
  -d 'did:key:z6Mkm8NbvDnnxJ2t5zLGSkYGCWZiqq11Axr58xQ3ZG1Jss3z'

did:key:z6Mkm8NbvDnnxJ2t5zLGSkYGCWZiqq11Axr58xQ3ZG1Jss3z

The SSI Kit can also be used as direct dependency for JVM-based applications. In this case an existing application can easily be enhanced with SSI functionality.