README.md

April 14, 2026 · View on GitHub

Identity Development Kit (IDK)

A Kotlin Multiplatform SDK for Digital Identity

Features • Quick Start • Modules • Services • Docs • Contributing

Overview

IDK is an open-core Kotlin Multiplatform SDK for digital identity. It covers credential issuance and verification, identity proofing, trust establishment, and secure data exchange. One codebase compiles to Android, iOS, JVM, JavaScript (browser and Node.js), WebAssembly, and Linux native.

You can use IDK on its own to build wallets, verifiers, issuers, and identity services. It also serves as the foundation under Sphereon's commercial Enterprise Development Kit (EDK).

Full documentation: docs.sphereon.com/idk.

Features

Each item links to its guide on the documentation site.

Decentralized Identifiers (DIDs)

Create, resolve, and manage W3C DIDs
Pluggable DID method support
Built-in: did:key, did:jwk, did:web

Mobile Documents (mDoc / mDL)

ISO/IEC 18013-5 compliant
BLE, NFC, and HTTP/WebSocket transports
Engagement and transfer managers
Reader and holder functionality

Cryptographic Services

JOSE / COSE (JWS, JWE, JWT)
Signing and verification
Pluggable KMS providers: AWS, Azure, mobile keystores, REST
Identifier resolution (DID, x5c, JWK)

Trust Management

OpenID for Verifiable Presentations (OID4VP)

OpenID for Verifiable Credential Issuance (OID4VCI)

Issuer and holder implementations
Authorization code, pre-authorized code, deferred issuance
Notification endpoint

SD-JWT

Selective disclosure issuance
Verification, key binding, status lists

OAuth 2.0 / OpenID Connect

OAuth2 client
Authorization server (auth-code, client-credentials, pre-authorized-code, token exchange, introspection, revocation, PAR)
DPoP and PKCE
JWT validation

Identity Proofing and Reconciliation

Document verification, biometrics, OTP
Policy-driven identity reconciliation

Developer Experience

Compile-time dependency injection via Metro
Configuration system with multi-tenancy
Event system, scoped logging
Ktor integration

Supported Platforms

Platform	Status	Notes
JVM	Supported	Java 21+
Android	Supported	API 27+ (Android 8.1+); BLE, NFC HCE, Android Keystore
iOS	Supported	arm64, x64, simulator-arm64; CoreBluetooth, CoreNFC, Secure Enclave
JavaScript	Supported	Browser and Node.js, ES modules, TypeScript definitions generated
WebAssembly	Supported	wasmJs (browser and Node.js), BigInt, TypeScript definitions
Linux	Supported	x64, server and CLI tooling

See Platform Setup for per-platform requirements.

Quick Start

Full installation and getting-started instructions: docs.sphereon.com/idk/guides/getting-started.

Prerequisites

JDK 21 or higher
Gradle 9.x (wrapper included)
Android SDK, compileSdk 35 (for Android targets)
Xcode 15+ (for iOS targets, macOS only)

Installation

Add the Sphereon Maven repository and dependencies to your build.gradle.kts:

repositories {
    mavenCentral()
    maven("https://nexus.sphereon.com/repository/sphereon-opensource-releases/")
    maven("https://nexus.sphereon.com/repository/sphereon-opensource-snapshots/")
}

dependencies {
    // Core API
    implementation("com.sphereon.idk:lib-core-api-public:0.25.0-SNAPSHOT")

    // Cryptography
    implementation("com.sphereon.idk:lib-crypto-core-public:0.25.0-SNAPSHOT")
    implementation("com.sphereon.idk:lib-crypto-core-impl:0.25.0-SNAPSHOT")

    // DIDs
    implementation("com.sphereon.idk:lib-did-resolver-impl:0.25.0-SNAPSHOT")
    implementation("com.sphereon.idk:lib-did-methods-key:0.25.0-SNAPSHOT")

    // mDoc
    implementation("com.sphereon.idk:lib-mdoc-core-public:0.25.0-SNAPSHOT")
    implementation("com.sphereon.idk:lib-mdoc-core-impl:0.25.0-SNAPSHOT")

    // OID4VCI / OID4VP / SD-JWT: add as needed
}

See the installation guide for per-platform setup and the modules reference for the full module catalogue.

npm packages

JavaScript and WebAssembly artefacts are published to npmjs under the @sphereon/idk-* scope. For example:

npm install @sphereon/idk-lib-core-api-public

Snapshots use the snapshot dist-tag (@sphereon/idk-foo@snapshot); released versions are on latest.

Building from Source

git clone https://github.com/Sphereon-Opensource/Identity-Development-Kit.git
cd Identity-Development-Kit
./gradlew build                     # full multiplatform build
./gradlew build -Dkmp.targets=jvm   # JVM only (~5 min)
./gradlew allTests                  # run all tests

On Windows, run ./gradlew --stop before rebuilding if you hit file-locking errors.

Library Modules

Modules follow the lib-<domain>-<feature>-{public,impl} convention. public modules contain interfaces and data models; impl modules contain implementations.

Full module reference: docs.sphereon.com/idk/guides/modules.

Core

Module	Description
`lib-core-api-public`	Core interfaces, `IdkResult`, command pattern, error types, tracing
`lib-core-api-default`	Default implementations of core APIs
`lib-core-events-public` / `-impl`	Event system for pub/sub
`lib-core-loggers-mobile-logger`	Mobile-friendly logger sink
`lib-conf-settings`	Multiplatform configuration management
`lib-conf-yaml`	YAML config source

Cryptography

Module	Description
`lib-crypto-core-public` / `-impl`	Core crypto operations, JWS, JWE, JWT
`lib-crypto-kms-provider-software`	Software-based key storage (ephemeral)
`lib-crypto-kms-provider-aws`	AWS KMS integration
`lib-crypto-kms-provider-azure`	Azure Key Vault / HSM integration
`lib-crypto-kms-provider-mobile`	iOS Keychain / Android Keystore
`lib-crypto-kms-provider-rest`	Remote KMS via REST API
`lib-crypto-kms-rest-server`	KMS REST server implementation

Decentralized Identifiers (DID)

Module	Description
`lib-did-core-public`	DID data models and interfaces
`lib-did-resolver-public` / `-impl`	Universal DID resolver
`lib-did-manager-public` / `-impl`	DID lifecycle management
`lib-did-methods-key`	`did:key` method support
`lib-did-methods-jwk`	`did:jwk` method support
`lib-did-methods-web`	`did:web` method support
`lib-did-persistence-memory`	In-memory DID storage
`lib-did-persistence-sqlite`	SQLite DID storage

Mobile Documents (mDoc / mDL)

Module	Description
`lib-mdoc-core-public` / `-impl`	ISO/IEC 18013-5 mDoc parsing and creation
`lib-mdoc-datatransfer`	Device engagement and session handling
`lib-mdoc-transport-ble`	Bluetooth Low Energy transport
`lib-mdoc-transport-nfc`	NFC transport (Android)
`lib-mdoc-transport-oid4vp`	OID4VP transport integration
`lib-mdoc-reader`	mDoc reader/verifier functionality

OpenID4VP / OpenID4VCI / OAuth2

Module	Description
`lib-openid-oid4vp-common-public`	Shared OID4VP types
`lib-openid-oid4vp-holder-public` / `-impl`	Wallet/holder OID4VP support
`lib-openid-oid4vp-verifier-public` / `-impl`	Verifier OID4VP support
`lib-openid-oid4vp-dcql`	DCQL query language
`lib-openid-oid4vci-common-public`	Shared OID4VCI types
`lib-openid-oid4vci-holder-public` / `-impl`	Holder OID4VCI flow
`lib-openid-oid4vci-issuer-public` / `-impl`	Issuer OID4VCI flow
`lib-oauth2-client-public` / `-impl`	OAuth2 client implementation
`lib-oauth2-server-authorization-public` / `-impl`	OAuth2 authorization server
`lib-oauth2-server-resource-public` / `-impl`	OAuth2 resource server
`lib-oauth2-jwt-validation-api` / `-impl`	JWT validation utilities

SD-JWT

Module	Description
`lib-sdjwt-public` / `-impl`	Selective Disclosure JWT

Identity Proofing

Module	Description
`lib-identity-resolution-public` / `-impl`	Identity resolution and lookup
`lib-identity-matching-public` / `-impl`	Probabilistic identity matching
`lib-identity-reconciliation-public` / `-impl`	Policy-driven reconciliation
`lib-identity-idv-public` / `-impl`	Identity verification orchestration

Data Link / Transport

Module	Description
`lib-data-link-ble`	BLE communication layer
`lib-data-link-nfc`	NFC communication layer
`lib-data-link-http-client-public` / `-impl`	HTTP client abstraction

Storage

Module	Description
`lib-data-store-kv-public` / `-impl`	Key-value storage abstraction
`lib-data-store-kv-impl-memory`	In-memory KV store
`lib-data-store-kv-impl-kottage`	Persistent KV store (Kottage)
`lib-data-store-blob-public` / `-impl-fs`	Blob storage (filesystem)
`lib-data-store-party-public` / `-impl`	Party / tenant data models

Trust

Module	Description
`lib-trust-etsi`	ETSI trust list support
`lib-trust-etsi-entities-public`	ETSI entities models
`lib-trust-x509`	X.509 certificate trust
`lib-trust-did`	DID-based trust
`lib-trust-oidfed`	OpenID Federation

Credential Design

Module	Description
`lib-credential-claims-mapper-public` / `-impl`	Claim mapping for credential payloads
`lib-data-store-credential-design-public` / `-impl`	Credential design registry

Server / Integration

Module	Description
`ktor-server-kotlin-inject`	Ktor + Metro DI integration

CBOR

Module	Description
`lib-cbor-public` / `-impl`	CBOR encoding/decoding

Services

IDK ships reference services that wrap the core libraries with HTTP adapters. Each has its own page on the documentation site.

Service	Module	Documentation
KMS REST	`services/kms`	docs.sphereon.com/idk/services/kms
Ktor base	`services/ktor`	docs.sphereon.com/idk/services/ktor
OAuth 2.0 Authorization Server	`services/oauth2-as/rest`	docs.sphereon.com/idk/services/oauth2-as
OID4VCI Issuer	`services/oid4vci-issuer/rest`	docs.sphereon.com/idk/services/oid4vci-issuer
OID4VP Verifier	`services/oid4vp-verifier/rest`	docs.sphereon.com/idk/services/oid4vp-verifier

The OID4VCI Holder REST service has moved to the Enterprise Development Kit. Holder library modules (lib-openid-oid4vci-holder-*) remain in IDK.

Services overview: docs.sphereon.com/idk/services/overview.

Architecture

IDK separates APIs from implementations:

lib/<domain>/
  ├── public/     # Interfaces, data models, contracts
  └── impl/       # Implementations (swappable)

Architecture deep-dive: docs.sphereon.com/idk/architecture.

Error Handling

IDK uses IdkResult<V, E> for explicit error handling instead of exceptions:

import com.sphereon.core.api.Ok
import com.sphereon.core.api.Err
import com.sphereon.core.api.error.IdkError

fun createDid(): IdkResult<String, IdkError> {
    return Ok("did:key:z6Mk...")
    // or: Err(IdkError.ILLEGAL_ARGUMENT_ERROR(message = "Invalid key type"))
}

when (val result = createDid()) {
    is Ok  -> println("Created: ${result.value}")
    is Err -> println("Failed: ${result.error.message}")
}

Dependency Injection

IDK uses Metro for compile-time DI across all platforms. Metro is a Kotlin compiler plugin and works on every Kotlin Multiplatform target the IDK ships to. See the DI app-setup guide and the scopes guide.

Scopes: AppScope > UserScope > SessionScope.

Documentation

Full documentation: docs.sphereon.com/idk.

Section	Link
Introduction	docs.sphereon.com/idk/introduction
Getting Started	docs.sphereon.com/idk/guides/getting-started
Installation	docs.sphereon.com/idk/guides/installation
Platform Setup	docs.sphereon.com/idk/guides/platform-setup
Architecture	docs.sphereon.com/idk/architecture
Module Reference	docs.sphereon.com/idk/guides/modules
Services	docs.sphereon.com/idk/services/overview
FAQ	docs.sphereon.com/idk/guides/faq

Generating local API docs (Dokka)

./gradlew dokkaGenerate

Output: build/dokka/html/index.html. The hosted Dokka build is also linked from the documentation site.

Build commands

Command	Description
`./gradlew build`	Build all modules (multiplatform)
`./gradlew build -Dkmp.targets=jvm`	JVM only (~5 min)
`./gradlew allTests`	Run all tests on configured targets
`./gradlew jvmTest`	Run JVM tests only
`./gradlew testDebugUnitTest`	Run Android unit tests
`./gradlew iosSimulatorArm64Test`	Run iOS simulator tests
`./gradlew dokkaGenerate`	Generate API documentation
`BUILD_XCFRAMEWORKS=true ./gradlew build`	Build with iOS XCFrameworks

Enterprise Development Kit (EDK)

Sphereon's proprietary product that extends the IDK with the layers required for production enterprise deployments. The IDK provides the identity primitives (cryptography, DIDs, verifiable credentials, SD-JWT, OID4VP, KMS, command/DI framework); the EDK adds:

Zero-trust authorization via the OpenID AuthZEN specification, with Cedarling (Cedar), OPA, and any AuthZEN-compliant PDP supported. Authorization is transparent: a PolicyCommandExtension intercepts every command before execution.
Identity verification and reconciliation: composable IDV workflows chaining OIDC, document scanning, biometric, and OTP verification; privacy-preserving identity matching with HMAC-hashed linking; policy-driven reconciliation; an auth bridge from wallet presentations to OAuth2/OIDC.
Microservice transport: dual transport that makes command execution location-transparent. The same command can run in-process or be forwarded to a remote service via HTTP RPC or gRPC, controlled by configuration.
Cloud configuration and secrets: cloud config providers (Azure App Configuration, REST), secret vaults (AWS Secrets Manager, Azure Key Vault, HashiCorp Vault), ${secret:vault:path} interpolation, offline cache.
Audit and compliance: structured audit logging with sensitive-data redaction, multiple output formats (JSON, CEF, OCSF), tamper evidence via hash chaining and signed checkpoints.

Verifiable Data Exchange (VDX)

The full platform on top of EDK and IDK. An enterprise identity and trust platform that unifies verifiable credentials, digital signatures, wallet-based authentication, and secure data exchange into a single deployable product, with management UIs, workflow orchestration, and operational tooling. Includes the Credential Designer, Issuer/Verifier Management consoles, wallet authentication flow, and white-label branding. Full platform documentation is in progress (Q2 2026).

Contributing

See CONTRIBUTING.md for the upstream-first PR flow and review process.

Open PRs against develop on this repo. Maintainers review here, apply the change in the internal repo with a Co-authored-by: trailer, and the mirror brings the result back. Your work appears on develop with the original attribution.

For security issues, follow the disclosure process in SECURITY.md. Do not open public PRs or issues for vulnerabilities.

License

Licensed under the Apache License, Version 2.0. See LICENSE for details.

_{Built by Sphereon. Creating Trust In A Digital World.}

Website • Documentation • GitHub