0
# JJWT API
1

2
JJWT API is the core API module of the JJWT (Java JWT) library, providing interfaces and contracts for creating and verifying JSON Web Tokens (JWTs) and JSON Web Keys (JWKs) on the JVM and Android platforms. This is a pure Java implementation based exclusively on JOSE Working Group RFC specifications including JWT (RFC 7519), JWS (RFC 7515), JWE (RFC 7516), JWK (RFC 7517), and related standards.
3

4
## Package Information
5

6
- **Package Name**: io.jsonwebtoken:jjwt-api
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Installation**: 
10
  ```xml
11
  <dependency>
12
      <groupId>io.jsonwebtoken</groupId>
13
      <artifactId>jjwt-api</artifactId>
14
      <version>0.12.6</version>
15
  </dependency>
16
  ```
17

18
## Core Imports
19

20
```java
21
import io.jsonwebtoken.Jwts;
22
import io.jsonwebtoken.JwtBuilder;
23
import io.jsonwebtoken.JwtParser;
24
import io.jsonwebtoken.Claims;
25
import io.jsonwebtoken.Jws;
26
```
27

28
For security and key management:
29

30
```java
31
import io.jsonwebtoken.security.Keys;
32
import io.jsonwebtoken.security.Jwks;
33
```
34

35
For IO utilities:
36

37
```java
38
import io.jsonwebtoken.io.Encoders;
39
import io.jsonwebtoken.io.Decoders;
40
```
41

42
## Basic Usage
43

44
### Creating a JWT
45

46
```java
47
import io.jsonwebtoken.Jwts;
48
import io.jsonwebtoken.security.Keys;
49
import javax.crypto.SecretKey;
50
import java.util.Date;
51

52
// Generate a secure key for HMAC-SHA algorithms
53
SecretKey key = Keys.secretKeyFor(Jwts.SIG.HS256);
54

55
// Create a JWT
56
String jwt = Jwts.builder()
57
    .subject("user123")
58
    .issuer("myapp")
59
    .expiration(new Date(System.currentTimeMillis() + 3600000)) // 1 hour
60
    .claim("role", "admin")
61
    .signWith(key)
62
    .compact();
63

64
System.out.println(jwt);
65
```
66

67
### Parsing and Validating a JWT
68

69
```java
70
import io.jsonwebtoken.Jwts;
71
import io.jsonwebtoken.Claims;
72
import io.jsonwebtoken.Jws;
73

74
// Parse and verify the JWT
75
Jws<Claims> jws = Jwts.parser()
76
    .verifyWith(key)
77
    .build()
78
    .parseSignedClaims(jwt);
79

80
// Access claims
81
Claims claims = jws.getPayload();
82
String subject = claims.getSubject();
83
String role = claims.get("role", String.class);
84

85
System.out.println("Subject: " + subject);
86
System.out.println("Role: " + role);
87
```
88

89
## Architecture
90

91
JJWT API follows a clean separation of concerns with several key components:
92

93
- **Factory Classes**: `Jwts`, `Keys`, `Jwks` provide entry points and standard algorithm instances
94
- **Builder Pattern**: Extensive use throughout for JWT construction (`JwtBuilder`) and parser configuration (`JwtParserBuilder`)
95
- **Type Safety**: Generic interfaces ensure compile-time validation and prevent runtime errors
96
- **Immutability**: All parsed tokens, claims, and headers are immutable value objects
97
- **Standards Compliance**: Full implementation of JOSE specifications with comprehensive algorithm support
98

99
## Capabilities
100

101
### JWT Operations
102

103
Core JWT building, parsing, and validation functionality including support for signed (JWS) and encrypted (JWE) tokens.
104

105
```java { .api }
106
// JWT Builder Factory
107
public static JwtBuilder builder();
108

109
// JWT Parser Factory  
110
public static JwtParserBuilder parser();
111

112
// Claims Builder Factory
113
public static ClaimsBuilder claims();
114

115
// Header Builder Factory
116
public static HeaderBuilder header();
117
```
118

119
[JWT Operations](./jwt-operations.md)
120

121
### Security and JWK Management
122

123
Comprehensive key management, JSON Web Key (JWK) support, and cryptographic algorithm interfaces for secure JWT operations.
124

125
```java { .api }
126
// Key Utilities
127
public static SecretKey hmacShaKeyFor(byte[] bytes);
128
public static SecretKey secretKeyFor(SignatureAlgorithm alg); // deprecated but available
129
public static KeyPair keyPairFor(SignatureAlgorithm alg); // deprecated but available
130
public static Password password(char[] password);
131

132
// Key Builders
133
public static SecretKeyBuilder builder(SecretKey key);
134
public static PrivateKeyBuilder builder(PrivateKey key);
135

136
// JWK Factory Methods
137
public static DynamicJwkBuilder<?, ?> builder();
138
public static JwkParserBuilder parser();
139
public static JwkSetBuilder set();
140
public static JwkSetParserBuilder setParser();
141
```
142

143
[Security and JWK Management](./security-jwk.md)
144

145
### IO Utilities
146

147
Encoding, decoding, and serialization utilities for Base64/Base64URL operations and custom JSON processing.
148

149
```java { .api }
150
// Standard Encoders (from Encoders class)
151
public static final Encoder<byte[], String> BASE64 = Encoders.BASE64;
152
public static final Encoder<byte[], String> BASE64URL = Encoders.BASE64URL;
153

154
// Standard Decoders (from Decoders class)
155
public static final Decoder<CharSequence, byte[]> BASE64 = Decoders.BASE64;
156
public static final Decoder<CharSequence, byte[]> BASE64URL = Decoders.BASE64URL;
157
```
158

159
[IO Utilities](./io-utilities.md)
160

161
### Types and Interfaces
162

163
Core JWT types including Claims, Headers, and token interfaces that represent parsed JWT content.
164

165
```java { .api }
166
// Core JWT Interface
167
public interface Jwt<H, P> {
168
    H getHeader();
169
    P getPayload();
170
    <T> T accept(JwtVisitor<T> visitor);
171
}
172

173
// Claims Interface  
174
public interface Claims extends Map<String, Object> {
175
    String getIssuer();
176
    String getSubject();
177
    Set<String> getAudience();
178
    Date getExpiration();
179
    // ... other standard claims
180
}
181
```
182

183
[Types and Interfaces](./types.md)
184

185
## Standard Algorithms
186

187
JJWT API provides constants for all standard JOSE algorithms:
188

189
### Signature Algorithms (Jwts.SIG)
190
- **HMAC**: HS256, HS384, HS512
191
- **RSA**: RS256, RS384, RS512, PS256, PS384, PS512  
192
- **ECDSA**: ES256, ES384, ES512
193
- **EdDSA**: EdDSA (Ed25519, Ed448)
194

195
### Encryption Algorithms (Jwts.ENC)
196
- **AES-GCM**: A128GCM, A192GCM, A256GCM
197
- **AES-CBC**: A128CBC-HS256, A192CBC-HS384, A256CBC-HS512
198

199
### Key Management Algorithms (Jwts.KEY)
200
- **Direct**: DIRECT
201
- **AES Key Wrap**: A128KW, A192KW, A256KW
202
- **RSA**: RSA1_5, RSA-OAEP, RSA-OAEP-256
203
- **ECDH**: ECDH-ES, ECDH-ES+A128KW, ECDH-ES+A192KW, ECDH-ES+A256KW
204
- **PBES2**: PBES2-HS256+A128KW, PBES2-HS384+A192KW, PBES2-HS512+A256KW
205

206
### Compression Algorithms (Jwts.ZIP)
207
- **DEFLATE**: DEF
208
- **GZIP**: GZIP