Getting Started

The Kiwa eLicense Holder SDK provides a comprehensive toolkit for integrating with Kiwa's e-license services. It offers a structured way to interact with various Kiwa APIs, including authentication and license holder management. The SDK is built using Kotlin Multiplatform and leverages both a command-based and more traditional services architecture for clear and maintainable interactions.

note

This is proprietary software subject to a license agreement restricted to Kiwa customers only!

The Kiwa eLicense SDK provides Kiwa customers a multiplatform SDK for the Kiwa eLicense solution.

info

The Kiwa eLicense SDK builds on the Identity Development Kit (IDK). For IDK documentation, please visit the separate IDK product section. The Kiwa SDK has all required dependencies including the IDK already included.

Installation

See Installation for detailed SDK installation instructions.

The below minimal artifact is required

dependencies {
  implementation("com.sphereon.kiwa:kiwa-holder-sdk-impl:0.6.0-SNAPSHOT")
  // implementation("com.sphereon.kiwa:kiwa-holder-sdk-public:0.6.0-SNAPSHOT") This dependency is also included in the impl dependency above
}

API Reference

See Kotlin API (new window) for the full API reference.

SDK Overview

The Kiwa eLicense SDK provides a structured interface for working with Kiwa's e-license APIs. It's organized around services and commands that encapsulate both high-level actions and low-level configuration, all built using Kotlin with dependency injection support.

3 main artifacts

The SDK is split into 2 main artifacts and one optional predefined component artifact.

The artifacts are:

• kiwa-sdk-holder-public
• kiwa-sdk-holder-impl
• kiwa-sdk-holder-all

The public artifact contains the high-level services and command interfaces and common code. The impl artifact contains the actual implementations that get injected. The all artifact contains both public and impl artifacts and also contains predefined dependency injection components.

High-Level Services

These are the entry points you'll typically interact with:

1. Authentication (AuthService):

• Handles operations related to wallet certificates, including requesting and managing client mTLS certificates required for secure API communication.
• Request certificate: Request a certificate to establish a secure connection (getWalletCertificate).

2. License Holder Management (HolderService):

Manages operations for license holders, such as:

• Assigning licenses: Assign a pre-existing license to a device/holder using an activation code and email (assignLicense).
• Issuing licenses: Retrieve new licenses available for the authenticated holder (issueLicense). The license data is typically returned in CBOR format.
• Confirming license issuance: Notify the backend that licenses have been successfully retrieved by the holder (confirmLicense).
• Decoding licenses: Parse CBOR-encoded license data into structured objects (decodeLicenses).

3. License verifications (VerifierService): Manages operations for local license verification, such as:

• Verify license: Verify a license both cryptographically and its validity dates, like issuance and expiration date (verifyLicense).

4. License presentation (PresentationService): Operations for license presentation to Relying Parties, meaning external parties that want to verify your license(s), such as:

• Engagement Manager: Create new engagement and transfer sessions to get your licenses verified with a remote party. For instance via Bluetooth Low Energy or NFC ( engagementManager).

Lower level exposed interfaces:

These lower-level components are available if you need to customize or extend SDK behavior:

5. API Environment Configuration (ApiEnvironmentConfigCommand):

• Dynamically configures API base URLs, endpoints, and subscription keys based on the target environment (e.g., DEV, TEST, ACC, PROD, CUSTOM).
• Ensures that API calls are directed to the correct Kiwa infrastructure.

6. HTTP Client Management (KiwaHttpFactory):

• Provides pre-configured Ktor HTTP clients for interacting with Kiwa APIs.
• Handles mTLS setup for secure communication with APIs like the Holder API.

7. Cryptographic Services (KiwaHolderServices): Manages underlying cryptographic operations, including:

• Key and certificate storage (in-memory).
• Key generation and management.
• Certificate Signing Request (CSR) generation.

SDK Architecture

Understanding the architecture will help you extend or customize the SDK effectively. Here’s an overview of the main building blocks:

• Services (AuthService, HolderService): High-level entry points that aggregate related commands.
• Commands (e.g., GetWalletCertificateCommand, AssignDeviceLicenseCommand, IssueLicenseCommand): Granular, self-contained units of work that interact with specific API endpoints or perform specific tasks. They follow an ISureCommand pattern, providing execute methods and handling results/errors.
• Data Classes: Used for request parameters and response objects for commands and API interactions.
• Dependency Injection: The SDK leverages dependency injection (e.g., using Anvil and Kotlin Inject) for managing service dependencies and scopes, allowing for Loosely coupled and highly cohesive code.

Module Structure

Here's how the SDK is organized:

Package	Description
com.sphereon.kiwa.elicense.sdk.auth	Authentication-related services and commands
com.sphereon.kiwa.elicense.sdk.holder	License holder-related services and commands
com.sphereon.kiwa.elicense.sdk.common	Shared types, configs, and environment definitions
com.sphereon.kiwa.elicense.sdk.http	HTTP client factory for Kiwa APIs
com.sphereon.kiwa.openapi.common	Helper utilities for the OpenAPI generated clients
com.sphereon.kiwa.openapi.authentication	Generated Kotlin client for the Kiwa Authentication API
com.sphereon.kiwa.openapi.licenseholder	Generated Kotlin client for the Kiwa License Holder API

This SDK aims to simplify the integration process with Kiwa's e-license platform by providing robust, well-defined interfaces and commands.

Configurations

The Kiwa eLicense Holder SDK uses the configuration abstraction of the Identity Development Kit. This means there are multiple ways to configure properties. In the Kiwa eLicense SDK, the following options are available by default:

• Properties files
• Programmatic maps
• Environment variables (always take precedence)

The properties can be set application-wide, per tenant, or even per principal. In the Kiwa eLicense SDK, currently only application-wide properties are exposed.

info

See the IDK Configuration section for mappings to internal property formats for environment variables For example, the internal property kiwa.subscription.key can both be written as kiwa_subscription_key and KIWA_SUBSCRIPTION_KEY as environment variables.

For the different services, the respective property values will be explained down below.

Available configuration properties

Property	Description	Example Values
kiwa.api.environment	Defines the default environment the SDK uses if not overridden per request. If set, it will be used unless a request-specific value is provided. Each environment must be provisioned before use! Kiwa manages the environment-specific details.	dev, test, acc, prod
kiwa.subscription.key	The Kiwa subscription key. The unique key will be provided by Kiwa, required to access Kiwa APIs.	abc123-key
kiwa.subscription.key.acc	Subscription key for the acc environment.	acc-abc123-key
kiwa.subscription.key.test	Subscription key for the test environment.	test-abc123-key
kiwa.subscription.key.prod	Subscription key for the prod environment.	prod-abc123-key

note

When using the e-license solution, you will have a subscription with Kiwa. You should have received a subscription key along with it. Your account manager can provide you with more information if needed.

Multi-tenancy

The Kiwa eLicense Holder SDK uses the Identity Development Kit, which in turn employs concepts like dependency injections, and also has a notion of multi-tenancy. Even if your app does not use multi-tenancy, you still need to initialize a tenant when calling into the Kiwa eLicense SDK services. This is because the dependency injection framework relies on these scopes. For instance, the ability to have different configuration values for different Kiwa environments depends on these scopes.

Since the Kiwa eLicense Holder SDK mainly targets mobile apps, full multi-tenancy is likely not needed. You can always opt to map to a single virtual tenant, or even use the anonymous context scope.

note

See the Identity Development Kit section about the three scopes present in every single application, including the Kiwa eLicense SDK.