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 ETSI trust lists X.509 certificate validation DID-based trust OpenID Federation

OpenID for Verifiable Presentations (OID4VP) Holder and verifier implementations DCQL query language Universal request handling 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

---

Related Projects

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