JWT Creation

/**
 * Returns a Json Web Token builder used to create and sign tokens.
 * @return a token builder
 */
public static JWTCreator.Builder create();

import com.auth0.jwt.JWT;
import com.auth0.jwt.algorithms.Algorithm;

Algorithm algorithm = Algorithm.HMAC256("secret");
String token = JWT.create()
    .withIssuer("auth0")
    .withSubject("user123")
    .sign(algorithm);

/**
 * Add a custom Header Claim value.
 * @param headerClaims the map containing the custom claims to be added to the header
 * @return this same Builder instance
 */
Builder withHeader(Map<String, Object> headerClaims);

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

/**
 * Add a specific Key Id ("kid") claim to the Header.
 * @param keyId the Key Id value
 * @return this same Builder instance
 */
Builder withKeyId(String keyId);

// Custom header claims
Map<String, Object> headerClaims = new HashMap<>();
headerClaims.put("typ", "JWT");
headerClaims.put("cty", "application/json");

String token = JWT.create()
    .withHeader(headerClaims)
    .withKeyId("key-1")
    .sign(algorithm);

// Header from JSON
String headerJson = "{\"typ\":\"JWT\",\"custom\":\"value\"}";
String token = JWT.create()
    .withHeader(headerJson)
    .sign(algorithm);

/**
 * Add a specific Issuer ("iss") claim to the Payload.
 * @param issuer the Issuer value
 * @return this same Builder instance
 */
Builder withIssuer(String issuer);

/**
 * Add a specific Subject ("sub") claim to the Payload.
 * @param subject the Subject value
 * @return this same Builder instance
 */
Builder withSubject(String subject);

/**
 * Add a specific Audience ("aud") claim to the Payload.
 * @param audience the Audience value
 * @return this same Builder instance
 */
Builder withAudience(String... audience);

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

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

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

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

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

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

/**
 * Add a specific JWT Id ("jti") claim to the Payload.
 * @param jwtId the JWT Id value
 * @return this same Builder instance
 */
Builder withJWTId(String jwtId);

import java.time.Instant;
import java.time.temporal.ChronoUnit;

// Standard claims with Date
Date expiresAt = new Date(System.currentTimeMillis() + 3600000); // 1 hour
String token = JWT.create()
    .withIssuer("https://my-app.com")
    .withSubject("user123")
    .withAudience("api1", "api2")
    .withExpiresAt(expiresAt)
    .withNotBefore(new Date())
    .withIssuedAt(new Date())
    .withJWTId("unique-token-id")
    .sign(algorithm);

// Standard claims with Instant
Instant now = Instant.now();
String token = JWT.create()
    .withIssuer("https://my-app.com")
    .withExpiresAt(now.plus(1, ChronoUnit.HOURS))
    .withNotBefore(now)
    .withIssuedAt(now)
    .sign(algorithm);

/**
 * Add a custom Claim value of type Boolean.
 * @param name the Claim's name
 * @param value the Claim's value
 * @return this same Builder instance
 */
Builder withClaim(String name, Boolean value);

/**
 * Add a custom Claim value of type Integer.
 * @param name the Claim's name
 * @param value the Claim's value
 * @return this same Builder instance
 */
Builder withClaim(String name, Integer value);

/**
 * Add a custom Claim value of type Long.
 * @param name the Claim's name
 * @param value the Claim's value
 * @return this same Builder instance
 */
Builder withClaim(String name, Long value);

/**
 * Add a custom Claim value of type Double.
 * @param name the Claim's name
 * @param value the Claim's value
 * @return this same Builder instance
 */
Builder withClaim(String name, Double value);

/**
 * Add a custom Claim value of type String.
 * @param name the Claim's name
 * @param value the Claim's value
 * @return this same Builder instance
 */
Builder withClaim(String name, String value);

/**
 * Add a custom Claim value of type Date.
 * @param name the Claim's name
 * @param value the Claim's value
 * @return this same Builder instance
 */
Builder withClaim(String name, Date value);

/**
 * Add a custom Claim value of type Instant.
 * @param name the Claim's name
 * @param value the Claim's value
 * @return this same Builder instance
 */
Builder withClaim(String name, Instant value);

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

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

/**
 * Add a custom null Claim to the Payload.
 * @param name the Claim's name
 * @return this same Builder instance
 */
Builder withNullClaim(String name);

// Various custom claim types
String token = JWT.create()
    .withClaim("role", "admin")
    .withClaim("age", 25)
    .withClaim("isActive", true)
    .withClaim("balance", 1234.56)
    .withClaim("lastLogin", new Date())
    .withClaim("metadata", Map.of("region", "us-east", "tier", "premium"))
    .withClaim("permissions", List.of("read", "write", "delete"))
    .withNullClaim("optional")
    .sign(algorithm);

/**
 * Add a custom Array Claim with String items.
 * @param name the Claim's name
 * @param items the Claim's value
 * @return this same Builder instance
 */
Builder withArrayClaim(String name, String[] items);

/**
 * Add a custom Array Claim with Integer items.
 * @param name the Claim's name
 * @param items the Claim's value
 * @return this same Builder instance
 */
Builder withArrayClaim(String name, Integer[] items);

/**
 * Add a custom Array Claim with Long items.
 * @param name the Claim's name
 * @param items the Claim's value
 * @return this same Builder instance
 */
Builder withArrayClaim(String name, Long[] items);

// Array claims
String[] roles = {"admin", "user", "guest"};
Integer[] scores = {100, 85, 92};
Long[] timestamps = {1234567890L, 1234567891L};

String token = JWT.create()
    .withArrayClaim("roles", roles)
    .withArrayClaim("scores", scores)
    .withArrayClaim("timestamps", timestamps)
    .sign(algorithm);

/**
 * Add custom Payload Claims to be included in the Payload.
 * @param payloadClaims the map containing the custom claims to be added to the payload
 * @return this same Builder instance
 */
Builder withPayload(Map<String, ?> payloadClaims);

/**
 * Add custom Payload Claims from a JSON string.
 * @param payloadClaimsJson the JSON string containing the custom claims to be added to the payload
 * @return this same Builder instance
 */
Builder withPayload(String payloadClaimsJson);

// Payload from Map
Map<String, Object> payloadClaims = new HashMap<>();
payloadClaims.put("user", "john");
payloadClaims.put("role", "admin");
payloadClaims.put("exp", System.currentTimeMillis() / 1000 + 3600);

String token = JWT.create()
    .withPayload(payloadClaims)
    .sign(algorithm);

// Payload from JSON
String payloadJson = "{\"user\":\"john\",\"role\":\"admin\",\"exp\":1234567890}";
String token = JWT.create()
    .withPayload(payloadJson)
    .sign(algorithm);

/**
 * Creates a new JWT and signs it with the given algorithm.
 * @param algorithm used to sign the JWT
 * @return a new JWT token
 * @throws IllegalArgumentException if the provided algorithm is null
 * @throws JWTCreationException if the claims could not be converted to a valid JSON or there was a problem with the signing key
 */
String sign(Algorithm algorithm) throws IllegalArgumentException, JWTCreationException;

import com.auth0.jwt.exceptions.JWTCreationException;

try {
    Algorithm algorithm = Algorithm.HMAC256("secret");
    String token = JWT.create()
        .withIssuer("auth0")
        .withSubject("user123")
        .sign(algorithm);
    
    // Use the token
    System.out.println("Generated token: " + token);
} catch (JWTCreationException exception) {
    // Invalid Signing configuration / Couldn't convert Claims
    System.err.println("Failed to create JWT: " + exception.getMessage());
}

/**
 * The JWTCreator class holds the sign method to generate a complete JWT (with Signature)
 * from a given Header and Payload content.
 * This class is thread-safe.
 */
public final class JWTCreator {
    
    /**
     * Builder class for constructing JWT tokens with fluent API.
     * All methods return the same Builder instance for method chaining.
     */
    public static class Builder {
        // All builder methods documented above
    }
}