kjwt
0.1.0indexedCreation, parsing, signing and encryption of JWTs (JWS/JWE); claim management, validation, Base64URL encoding/decoding, cryptographic primitives, and CI-ready tests and workflows.
5
Stars
—
Used by
dependents
—
Health
/ 100
KJWT
A JSON Web Token (JWT) is a compact, URL-safe standard for representing data to be transferred between two parties. The data within a JWT - referred to as claims - is encoded as a JSON object that serves as the payload for either a JSON Web Signature (JWS) or a JSON Web Encryption (JWE) structure. This design allows claims to be digitally signed for integrity (using a Message Authentication Code or MAC) and/or encrypted for privacy.
The most common JWT format is a string composed of three dot-separated segments: header, payload, and signature. This structure represents a JWS, as defined by RFC 7515. In this format, the header and payload are Base64URL-encoded, meaning they can be easily decoded by anyone to reveal their contents. The third segment, the signature, is also Base64URL-encoded and is used to verify that the first two parts of the token have not been tampered with.
While less common, JWTs can also follow the JWE format defined by RFC 7516, which consists of five dot-separated parts: header, encrypted key, initialization vector, ciphertext, and authentication tag. Unlike a JWS, where data is merely signed, a JWE encrypts the data. While the header remains decodable, the remaining segments are encrypted and cannot be read without the appropriate cryptographic key.
How about the other formats and RFCs?
The JWT is just a part of the JOSE family of standards. JOSE stands for JSON Object Signing and Encryption, and it groups several related RFCs that define how to sign, encrypt, and manage keys for JSON data. To support all of these features, the JOSE family includes a few different standards, such as:
- RFC 7519 (JWT) - JSON Web Token
While the JWT is a specific format for representing claims (payload), the JOSE standards provide the tools and specifications for creating, signing, encrypting, and managing those claims in a secure and interoperable way. The JWT is just one of the possible formats for representing claims, and it is designed to be compact and URL-safe.
When we first conceived KJWT, our goal was to support the JWS format of JWTs. However, as we developed the library, we realized that supporting the full range of JOSE standards would provide a more robust solution for users. Therefore, we decided to implement support for JWS, JWE, JWK, and JWA in addition to JWT. This allows KJWT to be a comprehensive library for working with JSON Web Tokens and related standards.
That said, our plan is not to implement all the RFCs. We will focus our efforts on implementing the ones that are necessary and relevant for JWT use cases. Some RFCs that are not relevant, or that explicitly state they should not be used with JWTs, may not be implemented. One example is the RFC-7797 - JSON Web Signature (JWS) Unencoded Payload Option which states in section 7 that it should not be used with JWTs.
Features
As of now, the library supports the following operations:
Setup
Add the library to your project and register a cryptography provider. The cryptography-provider-optimal artifact
auto-registers on startup and is the recommended choice:
// build.gradle.kts
dependencies {
implementation("co.touchlab:kjwt-core:<kjwt-version>")
// For usage with `Cryptography-Kotlin`, include the processor and the providers for it:
implementation("co.touchlab:kjwt-cryptography-kotlin-processor:<kjwt-version>")
implementation("dev.whyoleg.cryptography:cryptography-provider-optimal:<cryptography-kotlin-version>")
// Optional: Some extensions exist for the cryptography-kotlin library
implementation("co.touchlab:kjwt-cryptography-kotlin-processor-ext:<kjwt-version>")
// Mover providers will be added soon
}
Snapshot builds
Every merge to main is automatically published to the Maven snapshot repository. To use a snapshot version, add the
repository and use the -SNAPSHOT suffix:
// settings.gradle.kts
dependencyResolutionManagement {
repositories {
maven("https://central.sonatype.com/repository/maven-snapshots") {
mavenContent {
includeModuleByRegex("co\\.touchlab", "kjwt.*")
}
}
}
}
// build.gradle.kts
dependencies {
implementation("co.touchlab:kjwt:<kjwt-version>-SNAPSHOT") {
isChanging = true
}
}
Why another library?
There are two common reference points in the KMP ecosystem:
Signum is a community KMP library that supports many cryptographic operations, including JWT. It is more feature-rich and supports many algorithms, but it requires Android SDK 30+ — a hard limit for apps that need to support older devices.
Cryptography Kotlin takes a different approach: it is a low-level library whose goal is to expose cryptographic primitives across KMP targets, not to implement protocols on top of them. It is an excellent building block, but it does not give you a JWT API.
KJWT fills that gap. It provides a high-level, easy-to-use JWT API (JWS and JWE) that works across all major KMP platforms, with a migration-friendly design for teams moving from JJWT on the JVM.
We started by building KJWT directly on top of Cryptography Kotlin, and it remains the recommended crypto backend. Over time, however, we decoupled the JWT logic from any specific crypto implementation. The cryptographic layer is now pluggable: if your project already uses a different library for cryptography, you can write a thin processor for it and plug it into KJWT without changing anything else. This makes KJWT useful even in projects where the crypto stack is already decided.
One concrete motivation for this design was hardware-backed cryptography. Signum supports hardware-backed operations, which is a compelling feature — but it comes at the cost of requiring Android SDK 30+. With KJWT's pluggable architecture, you can implement a processor backed by hardware security when your app's minimum SDK allows it, while users on older Android versions continue to use a standard software-backed provider. The JWT layer stays the same regardless of which processor is underneath.
Going forward, we plan to ship first-party processors for hardware-backed cryptography and other provider types, so you get the benefits of those integrations without having to implement them yourself.
Aren't there enough standards already?
Usage
All actions were designed to be chainable, and start from the Jwt (import co.touchlab.kjwt.Jwt) object. It is the
entrypoint for most JWT operations. In that object, you will find methods to build and parse JWTs.
Building a JWT
The most common usage of JWTs is to generate signed tokens. You can achieve this by using the .signWith(...) method
when building a JWT.
val signingKey = SigningAlgorithm.HS256.newKey()
val token: JwtInstance = Jwt.builder()
.subject("1234567890")
.signWith(signingKey)
The result of the operation is a JwtInstance object. That object is a Kotlin representation of the JWT. You can use
it to access the defined claims and headers, as well as generate the famous compact version of the JWT.
val token: JwtInstance = // build the token as shown above
val serialized: String = token.compact()
// This call will generate the string version of the JWT, in the compact format
// Note: the compact format is the one split by the dots, with the header, payload and signature encoded in Base64URL
// format. It will look like this:
// <header>.<payload>.<signature> 👈This is the compact format template 👇And this is a real example
// eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.yaquqtp1qJ9uDVaWMdRtujneuFqIBkImorBu9hdLVl4
Parsing a JWT
Another common usage of JWTs is to verify the authenticity of a token. If you are a backend application, you need to ensure that the user hasn't modified the token on their side. That is achieved by verifying the signature of the token.
val compactToken: String = //
val jwtParser = Jwt.parser()
.verifyWith(signingKey)
.build()
val parsedToken = jwtParser.parse(compactToken)
Note that if the content has been changed on the client side, the signature will be invalid and the parsing will throw an exception. If the parse succeeds, the token is valid and ready to be used.
// Use content from the JWT:
val subject = parsedToken.payload.subjectOrNull
Keys
As you probably noticed, we skipped the keys part in the previous examples. The main reason for that is that we do not implement any cryptographic operations. Instead, we rely on the Cryptography Kotlin library. It's an amazing and robust library that provides a wide range of cryptographic operations, and providers for most of the Kotlin Multiplatform targets.
KJWT ships extension functions on each algorithm object that generate or decode keys without
requiring you to touch the cryptography-kotlin API directly:
import co.touchlab.kjwt.model.algorithm.SigningAlgorithm
// Generate a new random HMAC key
val key = SigningAlgorithm.HS256.newKey()
// Decode an HMAC key from existing bytes
val key = SigningAlgorithm.HS256.parse(myKeyBytes)
// Generate an RSA key pair (also available for RS384/RS512, PS*, ES*)
val key = SigningAlgorithm.RS256.newKey()
// Decode individual RSA/ECDSA keys
val key = SigningAlgorithm.RS256.parsePublicKey(pemBytes) // verify only
val key = SigningAlgorithm.RS256.parsePrivateKey(pemBytes)
key = SigningAlgorithm.RS256.parseKeyPair(pubPem, privPem)
The returned SigningKey can be passed directly to signWith or verifyWith:
val key = SigningAlgorithm.HS256.parse(myKeyBytes)
val token: JwtInstance = Jwt.builder()
.subject("1234567890")
.signWith(key) // Use the key to sign the token
val jwtParser = Jwt.parser()
.verifyWith(key) // Use the key to verify the token
.build()
val compactToken: String = // ...
val parsedToken = jwtParser.parse(compactToken) // Token will get verified using the key used in the builder
If you prefer to work with cryptography-kotlin directly, you can also construct keys manually
using its API and pass them to signWith / verifyWith. For a full reference of all key helper
overloads, see the usage guide.
More features
For a more detailed list of features, check out the usage documentation available at the docs.