kjwt-core/co.touchlab.kjwt.builder/JwtBuilder

JwtBuilder

class JwtBuilder(jsonInstance: Json)(source)

Fluent builder for creating JWS (signed) and JWE (encrypted) compact tokens.

Example — signed:

val signingKey = SigningAlgorithm.HS256.newKey()
val token = Jwt.builder()
    .subject("user123")
    .issuer("myapp")
    .expiration(Clock.System.now() + 1.hours)
    .signWith(signingKey)

Example — encrypted:

val encKey = EncryptionAlgorithm.RsaOaep256.newKey()
val token = Jwt.builder()
    .subject("user123")
    .encryptWith(encKey, EncryptionContentAlgorithm.A256GCM)

Constructors

constructor(jsonInstance: Json)

Functions

fun audience(vararg aud: String): JwtBuilder

Sets the audience (aud) claim.

fun build(): JwtInstance.Jws

Builds and returns an unsecured JWS token with alg=none and an empty signature.

inline fun <T> claim(name: String, value: T): JwtBuilder

Sets a typed claim, inferring the serializer from the reified type T.

fun claim(name: String, value: JsonElement): JwtBuilder

Sets a raw claim using a pre-built JsonElement.

fun <T> claim(name: String, serializer: SerializationStrategy<T>, value: T?): JwtBuilder

Sets a typed claim using an explicit SerializationStrategy.

fun claims(block: JwtPayload.Builder.() -> Unit): JwtBuilder

Configures multiple claims at once using a DSL block applied to JwtPayload.Builder.

fun contentType(cty: String): JwtBuilder

Sets the content type (cty) header parameter.

suspend fun encryptWith(registry: JwtProcessorRegistry, keyAlgorithm: EncryptionAlgorithm, contentAlgorithm: EncryptionContentAlgorithm, keyId: String? = null): JwtInstance.Jwe

Looks up the public key from registry and builds a JWE compact serialization.

encryptWithJweProcessor

suspend fun encryptWithJweProcessor(processor: JweEncryptor, contentAlgorithm: EncryptionContentAlgorithm, keyId: String? = processor.keyId): JwtInstance.Jwe

Suspends, encrypts the token using the given JweEncryptor, and returns the JWE compact serialization.

fun expiration(exp: Instant): JwtBuilder

Sets the expiration time (exp) claim.

fun expiresIn(duration: Duration): JwtBuilder

Sets the expiration time (exp) claim relative to the current time.

inline fun <T> header(value: T): JwtBuilder

Merges all fields from value into the JOSE header, inferring the serializer from the reified type T.

fun header(block: JwtHeader.Builder.() -> Unit): JwtBuilder

Configures JOSE header fields using a DSL block applied to JwtHeader.Builder.

inline fun <T> header(name: String, value: T): JwtBuilder

Sets a typed extra header parameter, inferring the serializer from the reified type T.

fun header(name: String, value: JsonElement): JwtBuilder

Sets a raw extra header parameter using a pre-built JsonElement.

fun <T> header(serializer: SerializationStrategy<T>, value: T): JwtBuilder

Merges all fields from value into the JOSE header, encoded using serializer.

fun <T> header(name: String, serializer: SerializationStrategy<T>, value: T?): JwtBuilder

Sets a typed extra header parameter using an explicit SerializationStrategy.

fun id(jti: String): JwtBuilder

Sets the JWT ID (jti) claim.

fun issuedAt(iat: Instant): JwtBuilder

Sets the issued-at (iat) claim.

fun issuedNow(): JwtBuilder

Sets the issued-at (iat) claim to the current time.

fun issuer(iss: String): JwtBuilder

Sets the issuer (iss) claim.

fun notBefore(nbf: Instant): JwtBuilder

Sets the not-before (nbf) claim.

fun notBeforeNow(): JwtBuilder

Sets the not-before (nbf) claim to the current time.

inline fun <T> payload(value: T): JwtBuilder

Merges all fields from value into the payload, inferring the serializer from the reified type T.

fun <T> payload(serializer: SerializationStrategy<T>, value: T): JwtBuilder

Merges all fields from value into the payload, encoded using serializer.

@ExperimentalUuidApi

fun randomId(): JwtBuilder

Sets the JWT ID (jti) claim to a randomly generated UUID.

suspend fun signWith(integrityProcessor: JwsSigner, keyId: String? = integrityProcessor.keyId): JwtInstance.Jws

Suspends, signs the token using the given JwsSigner, and returns the JWS compact serialization.

suspend fun signWith(algorithm: SigningAlgorithm, registry: JwtProcessorRegistry, keyId: String? = null): JwtInstance.Jws

Looks up the private key from registry and builds a JWS compact serialization.

fun subject(sub: String): JwtBuilder

Sets the subject (sub) claim.

fun type(typ: String): JwtBuilder

Sets the token type (typ) header parameter.