JJWT API
Documentation

Installation #installation

Add the following dependencies to your build file. Include only the implementation you need.

Maven

XML<!-- Core API -->
<dependency>
  <groupId>io.jsonwebtoken</groupId>
  <artifactId>jjwt-api</artifactId>
  <version>0.12.6</version>
</dependency>

<!-- Runtime: choose jackson, gson, or orgjson -->
<dependency>
  <groupId>io.jsonwebtoken</groupId>
  <artifactId>jjwt-impl</artifactId>
  <version>0.12.6</version>
  <scope>runtime</scope>
</dependency>
<dependency>
  <groupId>io.jsonwebtoken</groupId>
  <artifactId>jjwt-jackson</artifactId>
  <version>0.12.6</version>
  <scope>runtime</scope>
</dependency>

Gradle

Groovyimplementation 'io.jsonwebtoken:jjwt-api:0.12.6'
runtimeOnly  'io.jsonwebtoken:jjwt-impl:0.12.6'
runtimeOnly  'io.jsonwebtoken:jjwt-jackson:0.12.6'

Quick Start #quickstart

Create and verify a signed JWT in under 10 lines of code.

Create a Token

Javaimport io.jsonwebtoken.Jwts;
import io.jsonwebtoken.security.Keys;
import javax.crypto.SecretKey;

// Generate a secure key (store it safely!)
SecretKey key = Keys.hmacShaKeyFor(secretBytes); // or Keys.secretKeyFor(SignatureAlgorithm.HS256)

String jwt = Jwts.builder()
    .subject("user123")
    .issuer("myapp")
    .issuedAt(new Date())
    .expiration(new Date(System.currentTimeMillis() + 86_400_000L)) // 1 day
    .claim("role", "admin")
    .signWith(key)
    .compact();

Parse & Verify a Token

JavaClaims claims = Jwts.parser()
    .verifyWith(key)
    .build()
    .parseSignedClaims(jwt)
    .getPayload();

String subject = claims.getSubject(); // "user123"
String role    = claims.get("role", String.class); // "admin"

Jwts Factory #jwts

The Jwts class is the main entry point. All operations start here.

JWT Builder #builder

Fluent API for constructing a token. Call compact() at the end to get the serialized string.

JavaJwts.builder()
    .header().add("kid", "my-key-id").and()
    ...

Java// Auto algorithm selection (recommended)
.signWith(secretKey)

// Explicit algorithm
.signWith(secretKey, Jwts.SIG.HS512)

// RSA / EC private key
.signWith(privateKey, Jwts.SIG.RS256)

JavaSecretKey aesKey = Jwts.KEY.A256GCMKW.key().build();

String jwe = Jwts.builder()
    .subject("alice")
    .encryptWith(aesKey, Jwts.KEY.A256GCMKW, Jwts.ENC.A256GCM)
    .compact();

Claims Interface #claims

The Claims interface extends Map<String, Object> and provides typed accessors for all registered claims.

JWT Parser #parser

All parsing starts with Jwts.parser(). The builder configures verification and then creates an immutable, thread-safe parser.

JwtParserBuilder Methods

JwtParser Parse Methods

Java// Thread-safe parser — create once, reuse everywhere
JwtParser parser = Jwts.parser()
    .verifyWith(publicKey)
    .requireIssuer("auth-service")
    .clockSkewSeconds(30)
    .build();

// Parse
Jws<Claims> jws = parser.parseSignedClaims(token);
Claims payload  = jws.getPayload();
JwsHeader header = jws.getHeader();

Keys & Key Generation #keys

Use the Keys utility class to safely generate or construct cryptographic keys.

Javaimport io.jsonwebtoken.security.Keys;

// ── HMAC Secret Keys ───────────────────────────────────────────
SecretKey hs256 = Jwts.SIG.HS256.key().build();
SecretKey hs384 = Jwts.SIG.HS384.key().build();
SecretKey hs512 = Jwts.SIG.HS512.key().build();

// From existing bytes (must be long enough for chosen alg)
SecretKey key = Keys.hmacShaKeyFor(Decoders.BASE64.decode(base64Secret));

// ── RSA Key Pair ───────────────────────────────────────────────
KeyPair rsaPair = Jwts.SIG.RS256.keyPair().build();  // 2048-bit
KeyPair ps512   = Jwts.SIG.PS512.keyPair().build();  // 4096-bit

// ── EC Key Pair ────────────────────────────────────────────────
KeyPair ec256 = Jwts.SIG.ES256.keyPair().build();   // P-256
KeyPair ec384 = Jwts.SIG.ES384.keyPair().build();   // P-384
KeyPair ec512 = Jwts.SIG.ES512.keyPair().build();   // P-521

// ── EdDSA (Ed25519) ────────────────────────────────────────────
KeyPair ed25519 = Jwts.SIG.Ed25519.keyPair().build();

HMAC Signature Algorithms #hmac

Available via Jwts.SIG.*. All require a SecretKey.

RSA Signature Algorithms #rsa

Sign with a PrivateKey, verify with the corresponding PublicKey.

Elliptic Curve Algorithms #ec

EdDSA (OKP) Algorithms #eddsa

Requires JDK 15+ or Bouncy Castle on older JDKs.

JSON Web Encryption (JWE) #jwe

JJWT supports full JWE token creation and parsing. JWE requires two algorithm choices:

Java// ── Encrypt ────────────────────────────────────────────────────
SecretKey encKey = Jwts.ENC.A256GCM.key().build();

String jwe = Jwts.builder()
    .subject("bob")
    .encryptWith(encKey, Jwts.KEY.A256GCMKW, Jwts.ENC.A256GCM)
    .compact();

// ── Decrypt ────────────────────────────────────────────────────
Claims claims = Jwts.parser()
    .decryptWith(encKey)
    .build()
    .parseEncryptedClaims(jwe)
    .getPayload();

JWE Key Algorithms #jwe-algorithms

JWE Content Encryption #jwe-enc

Exceptions #exceptions

All JJWT exceptions extend JwtException. Handle them to give meaningful error responses.

Javatry {
    Claims claims = parser.parseSignedClaims(token).getPayload();
} catch (ExpiredJwtException e) {
    // 401 - token expired
} catch (SignatureException e) {
    // 401 - tampered token
} catch (MalformedJwtException e) {
    // 400 - bad token format
} catch (JwtException e) {
    // 401 - catch-all
}

Compression #compression

Reduce token size when claims are large. Available via Jwts.ZIP.

JavaString compressedJwt = Jwts.builder()
    .claims(largeClaims)
    .compressWith(Jwts.ZIP.DEF)
    .signWith(key)
    .compact();

// Decompression is automatic when parsing
Claims claims = Jwts.parser()
    .verifyWith(key)
    .build()
    .parseSignedClaims(compressedJwt)
    .getPayload();

Migration Guide (0.11 → 0.12) #migration

Version 0.12 introduces a cleaner, more type-safe API. Key breaking changes: