0
# JWT Creation
1

2
Comprehensive JWT creation functionality providing a fluent builder API for constructing and signing JWT tokens with support for standard and custom claims.
3

4
## Capabilities
5

6
### JWT Creation Builder
7

8
Creates a JWT builder instance for constructing tokens with claims and signing.
9

10
```java { .api }
11
/**
12
 * Returns a Json Web Token builder used to create and sign tokens.
13
 * @return a token builder
14
 */
15
public static JWTCreator.Builder create();
16
```
17

18
**Usage Example:**
19

20
```java
21
import com.auth0.jwt.JWT;
22
import com.auth0.jwt.algorithms.Algorithm;
23

24
Algorithm algorithm = Algorithm.HMAC256("secret");
25
String token = JWT.create()
26
    .withIssuer("auth0")
27
    .withSubject("user123")
28
    .sign(algorithm);
29
```
30

31
### Header Configuration
32

33
Configure JWT header claims including algorithm, type, content type, and key ID.
34

35
```java { .api }
36
/**
37
 * Add a custom Header Claim value.
38
 * @param headerClaims the map containing the custom claims to be added to the header
39
 * @return this same Builder instance
40
 */
41
Builder withHeader(Map<String, Object> headerClaims);
42

43
/**
44
 * Add a custom Header Claim value from a JSON string.
45
 * @param headerClaimsJson the JSON string containing the custom claims to be added to the header
46
 * @return this same Builder instance
47
 */
48
Builder withHeader(String headerClaimsJson);
49

50
/**
51
 * Add a specific Key Id ("kid") claim to the Header.
52
 * @param keyId the Key Id value
53
 * @return this same Builder instance
54
 */
55
Builder withKeyId(String keyId);
56
```
57

58
**Usage Examples:**
59

60
```java
61
// Custom header claims
62
Map<String, Object> headerClaims = new HashMap<>();
63
headerClaims.put("typ", "JWT");
64
headerClaims.put("cty", "application/json");
65

66
String token = JWT.create()
67
    .withHeader(headerClaims)
68
    .withKeyId("key-1")
69
    .sign(algorithm);
70

71
// Header from JSON
72
String headerJson = "{\"typ\":\"JWT\",\"custom\":\"value\"}";
73
String token = JWT.create()
74
    .withHeader(headerJson)
75
    .sign(algorithm);
76
```
77

78
### Standard Claims
79

80
Configure standard JWT claims as defined in RFC 7519.
81

82
```java { .api }
83
/**
84
 * Add a specific Issuer ("iss") claim to the Payload.
85
 * @param issuer the Issuer value
86
 * @return this same Builder instance
87
 */
88
Builder withIssuer(String issuer);
89

90
/**
91
 * Add a specific Subject ("sub") claim to the Payload.
92
 * @param subject the Subject value
93
 * @return this same Builder instance
94
 */
95
Builder withSubject(String subject);
96

97
/**
98
 * Add a specific Audience ("aud") claim to the Payload.
99
 * @param audience the Audience value
100
 * @return this same Builder instance
101
 */
102
Builder withAudience(String... audience);
103

104
/**
105
 * Add a specific Expires At ("exp") claim to the Payload.
106
 * @param expiresAt the Expires At value
107
 * @return this same Builder instance
108
 */
109
Builder withExpiresAt(Date expiresAt);
110

111
/**
112
 * Add a specific Expires At ("exp") claim to the Payload.
113
 * @param expiresAt the Expires At value
114
 * @return this same Builder instance
115
 */
116
Builder withExpiresAt(Instant expiresAt);
117

118
/**
119
 * Add a specific Not Before ("nbf") claim to the Payload.
120
 * @param notBefore the Not Before value
121
 * @return this same Builder instance
122
 */
123
Builder withNotBefore(Date notBefore);
124

125
/**
126
 * Add a specific Not Before ("nbf") claim to the Payload.
127
 * @param notBefore the Not Before value
128
 * @return this same Builder instance
129
 */
130
Builder withNotBefore(Instant notBefore);
131

132
/**
133
 * Add a specific Issued At ("iat") claim to the Payload.
134
 * @param issuedAt the Issued At value
135
 * @return this same Builder instance
136
 */
137
Builder withIssuedAt(Date issuedAt);
138

139
/**
140
 * Add a specific Issued At ("iat") claim to the Payload.
141
 * @param issuedAt the Issued At value
142
 * @return this same Builder instance
143
 */
144
Builder withIssuedAt(Instant issuedAt);
145

146
/**
147
 * Add a specific JWT Id ("jti") claim to the Payload.
148
 * @param jwtId the JWT Id value
149
 * @return this same Builder instance
150
 */
151
Builder withJWTId(String jwtId);
152
```
153

154
**Usage Examples:**
155

156
```java
157
import java.time.Instant;
158
import java.time.temporal.ChronoUnit;
159

160
// Standard claims with Date
161
Date expiresAt = new Date(System.currentTimeMillis() + 3600000); // 1 hour
162
String token = JWT.create()
163
    .withIssuer("https://my-app.com")
164
    .withSubject("user123")
165
    .withAudience("api1", "api2")
166
    .withExpiresAt(expiresAt)
167
    .withNotBefore(new Date())
168
    .withIssuedAt(new Date())
169
    .withJWTId("unique-token-id")
170
    .sign(algorithm);
171

172
// Standard claims with Instant
173
Instant now = Instant.now();
174
String token = JWT.create()
175
    .withIssuer("https://my-app.com")
176
    .withExpiresAt(now.plus(1, ChronoUnit.HOURS))
177
    .withNotBefore(now)
178
    .withIssuedAt(now)
179
    .sign(algorithm);
180
```
181

182
### Custom Claims
183

184
Add custom claims to the JWT payload with type-safe value assignment.
185

186
```java { .api }
187
/**
188
 * Add a custom Claim value of type Boolean.
189
 * @param name the Claim's name
190
 * @param value the Claim's value
191
 * @return this same Builder instance
192
 */
193
Builder withClaim(String name, Boolean value);
194

195
/**
196
 * Add a custom Claim value of type Integer.
197
 * @param name the Claim's name
198
 * @param value the Claim's value
199
 * @return this same Builder instance
200
 */
201
Builder withClaim(String name, Integer value);
202

203
/**
204
 * Add a custom Claim value of type Long.
205
 * @param name the Claim's name
206
 * @param value the Claim's value
207
 * @return this same Builder instance
208
 */
209
Builder withClaim(String name, Long value);
210

211
/**
212
 * Add a custom Claim value of type Double.
213
 * @param name the Claim's name
214
 * @param value the Claim's value
215
 * @return this same Builder instance
216
 */
217
Builder withClaim(String name, Double value);
218

219
/**
220
 * Add a custom Claim value of type String.
221
 * @param name the Claim's name
222
 * @param value the Claim's value
223
 * @return this same Builder instance
224
 */
225
Builder withClaim(String name, String value);
226

227
/**
228
 * Add a custom Claim value of type Date.
229
 * @param name the Claim's name
230
 * @param value the Claim's value
231
 * @return this same Builder instance
232
 */
233
Builder withClaim(String name, Date value);
234

235
/**
236
 * Add a custom Claim value of type Instant.
237
 * @param name the Claim's name
238
 * @param value the Claim's value
239
 * @return this same Builder instance
240
 */
241
Builder withClaim(String name, Instant value);
242

243
/**
244
 * Add a custom Claim value of type Map.
245
 * @param name the Claim's name
246
 * @param map the Claim's value
247
 * @return this same Builder instance
248
 */
249
Builder withClaim(String name, Map<String, ?> map);
250

251
/**
252
 * Add a custom Claim value of type List.
253
 * @param name the Claim's name
254
 * @param list the Claim's value
255
 * @return this same Builder instance
256
 */
257
Builder withClaim(String name, List<?> list);
258

259
/**
260
 * Add a custom null Claim to the Payload.
261
 * @param name the Claim's name
262
 * @return this same Builder instance
263
 */
264
Builder withNullClaim(String name);
265
```
266

267
**Usage Examples:**
268

269
```java
270
// Various custom claim types
271
String token = JWT.create()
272
    .withClaim("role", "admin")
273
    .withClaim("age", 25)
274
    .withClaim("isActive", true)
275
    .withClaim("balance", 1234.56)
276
    .withClaim("lastLogin", new Date())
277
    .withClaim("metadata", Map.of("region", "us-east", "tier", "premium"))
278
    .withClaim("permissions", List.of("read", "write", "delete"))
279
    .withNullClaim("optional")
280
    .sign(algorithm);
281
```
282

283
### Array Claims
284

285
Add array-typed custom claims with type-safe element assignment.
286

287
```java { .api }
288
/**
289
 * Add a custom Array Claim with String items.
290
 * @param name the Claim's name
291
 * @param items the Claim's value
292
 * @return this same Builder instance
293
 */
294
Builder withArrayClaim(String name, String[] items);
295

296
/**
297
 * Add a custom Array Claim with Integer items.
298
 * @param name the Claim's name
299
 * @param items the Claim's value
300
 * @return this same Builder instance
301
 */
302
Builder withArrayClaim(String name, Integer[] items);
303

304
/**
305
 * Add a custom Array Claim with Long items.
306
 * @param name the Claim's name
307
 * @param items the Claim's value
308
 * @return this same Builder instance
309
 */
310
Builder withArrayClaim(String name, Long[] items);
311
```
312

313
**Usage Examples:**
314

315
```java
316
// Array claims
317
String[] roles = {"admin", "user", "guest"};
318
Integer[] scores = {100, 85, 92};
319
Long[] timestamps = {1234567890L, 1234567891L};
320

321
String token = JWT.create()
322
    .withArrayClaim("roles", roles)
323
    .withArrayClaim("scores", scores)
324
    .withArrayClaim("timestamps", timestamps)
325
    .sign(algorithm);
326
```
327

328
### Payload Configuration
329

330
Configure the entire JWT payload using Map or JSON string.
331

332
```java { .api }
333
/**
334
 * Add custom Payload Claims to be included in the Payload.
335
 * @param payloadClaims the map containing the custom claims to be added to the payload
336
 * @return this same Builder instance
337
 */
338
Builder withPayload(Map<String, ?> payloadClaims);
339

340
/**
341
 * Add custom Payload Claims from a JSON string.
342
 * @param payloadClaimsJson the JSON string containing the custom claims to be added to the payload
343
 * @return this same Builder instance
344
 */
345
Builder withPayload(String payloadClaimsJson);
346
```
347

348
**Usage Examples:**
349

350
```java
351
// Payload from Map
352
Map<String, Object> payloadClaims = new HashMap<>();
353
payloadClaims.put("user", "john");
354
payloadClaims.put("role", "admin");
355
payloadClaims.put("exp", System.currentTimeMillis() / 1000 + 3600);
356

357
String token = JWT.create()
358
    .withPayload(payloadClaims)
359
    .sign(algorithm);
360

361
// Payload from JSON
362
String payloadJson = "{\"user\":\"john\",\"role\":\"admin\",\"exp\":1234567890}";
363
String token = JWT.create()
364
    .withPayload(payloadJson)
365
    .sign(algorithm);
366
```
367

368
### Token Signing
369

370
Sign the constructed JWT with the specified algorithm to produce the final token string.
371

372
```java { .api }
373
/**
374
 * Creates a new JWT and signs it with the given algorithm.
375
 * @param algorithm used to sign the JWT
376
 * @return a new JWT token
377
 * @throws IllegalArgumentException if the provided algorithm is null
378
 * @throws JWTCreationException if the claims could not be converted to a valid JSON or there was a problem with the signing key
379
 */
380
String sign(Algorithm algorithm) throws IllegalArgumentException, JWTCreationException;
381
```
382

383
**Usage Examples:**
384

385
```java
386
import com.auth0.jwt.exceptions.JWTCreationException;
387

388
try {
389
    Algorithm algorithm = Algorithm.HMAC256("secret");
390
    String token = JWT.create()
391
        .withIssuer("auth0")
392
        .withSubject("user123")
393
        .sign(algorithm);
394
    
395
    // Use the token
396
    System.out.println("Generated token: " + token);
397
} catch (JWTCreationException exception) {
398
    // Invalid Signing configuration / Couldn't convert Claims
399
    System.err.println("Failed to create JWT: " + exception.getMessage());
400
}
401
```
402

403
## Types
404

405
```java { .api }
406
/**
407
 * The JWTCreator class holds the sign method to generate a complete JWT (with Signature)
408
 * from a given Header and Payload content.
409
 * This class is thread-safe.
410
 */
411
public final class JWTCreator {
412
    
413
    /**
414
     * Builder class for constructing JWT tokens with fluent API.
415
     * All methods return the same Builder instance for method chaining.
416
     */
417
    public static class Builder {
418
        // All builder methods documented above
419
    }
420
}
421
```