How to sign a JWT with ES256 in Kotlin

1// build.gradle.kts
2dependencies {
3    implementation("io.jsonwebtoken:jjwt-api:0.13.0")
4    runtimeOnly("io.jsonwebtoken:jjwt-impl:0.13.0")
5    runtimeOnly("io.jsonwebtoken:jjwt-gson:0.13.0") // or jjwt-jackson
6}

1import io.jsonwebtoken.Jwts
2import java.io.File
3import java.security.KeyFactory
4import java.security.spec.PKCS8EncodedKeySpec
5import java.time.Instant
6import java.util.Base64
7import java.util.Date
8 
9fun main() {
10    val pem = File("key.pem").readText()
11    val pkcs8 = Base64.getMimeDecoder().decode(pem.replace(Regex("-----[^-]+-----"), ""))
12    val privateKey = KeyFactory.getInstance("EC").generatePrivate(PKCS8EncodedKeySpec(pkcs8))
13 
14    val now = Instant.now()
15    val token = Jwts.builder()
16        .header().keyId("2026-10").type("JWT").and()
17        .issuer("https://issuer.example.com")
18        .subject("user-42")
19        .audience().add("api://orders").and()
20        .issuedAt(Date.from(now))
21        .expiration(Date.from(now.plusSeconds(15 * 60)))
22        .signWith(privateKey, Jwts.SIG.ES256) // checks that the key is P-256
23        .compact()
24 
25    println(token)
26}

How it works

1. The PKCS#8 PEM body is loaded with KeyFactory.getInstance("EC"); JJWT signs with any JCA PrivateKey.
2. .header().keyId(…).type("JWT").and() writes kid and typ; issuer, subject, audience().add(…), issuedAt and expiration write the claims.
3. signWith(privateKey, Jwts.SIG.ES256) checks that the key is a 256-bit EC key and produces the 64-byte JWS signature.
4. Code compiles against jjwt-api alone; jjwt-impl and a JSON module (jjwt-gson or jjwt-jackson) are needed only at runtime.

Gotchas

• Forgetting jjwt-impl compiles fine and fails at the first Jwts.builder(): UnknownClassException: Unable to load class named [io.jsonwebtoken.impl.DefaultJwtBuilder$Supplier] … Have you remembered to include the jjwt-impl.jar in your runtime classpath?.
• audience().add(…) writes aud as an array even for one value. audience().single(…) writes a string but is deprecated; prefer the array unless a consumer cannot read it.
• A P-384 key with Jwts.SIG.ES256 fails with SignatureException: Unable to compute ES256 signature. Cause: The provided Elliptic Curve signing key size (aka order bit length) is 384 bits (48 bytes), but the 'ES256' algorithm requires EC Keys with 256 bits (32 bytes)….
• JJWT 0.12 renamed the builder methods (setSubject → subject, setExpiration → expiration) and replaced the SignatureAlgorithm enum with Jwts.SIG. Code written for 0.11 still compiles against 0.13, with a deprecation warning on every one of those calls — update it before they are removed.

Related recipes

• How to sign a JWT with ES256 in Java
• How to verify a JWT with a JWKS in Kotlin
• How to compute a JWK thumbprint (RFC 7638) in Kotlin
• How to sign and verify Ed25519 signatures in Kotlin