JwtBuilder (JJWT :: API 0.11.2 API)

All Superinterfaces:

ClaimsMutator<JwtBuilder>
```
public interface JwtBuilder
extends ClaimsMutator<JwtBuilder>
```
A builder for constructing JWTs.

Since:

0.1

Method Summary

Methods
Modifier and Type	Method and Description
`JwtBuilder`	`addClaims(Map<String,Object> claims)` Adds all given name/value pairs to the JSON Claims in the payload.
`JwtBuilder`	`base64UrlEncodeWith(Encoder<byte[],String> base64UrlEncoder)` Perform Base64Url encoding with the specified Encoder.
`JwtBuilder`	`claim(String name, Object value)` Sets a custom JWT Claims parameter value.
`String`	`compact()` Actually builds the JWT and serializes it to a compact, URL-safe string according to the JWT Compact Serialization rules.
`JwtBuilder`	`compressWith(CompressionCodec codec)` Compresses the JWT body using the specified `CompressionCodec`.
`JwtBuilder`	`serializeToJsonWith(Serializer<Map<String,?>> serializer)` Performs object-to-JSON serialization with the specified Serializer.
`JwtBuilder`	`setAudience(String aud)` Sets the JWT Claims `aud` (audience) value.
`JwtBuilder`	`setClaims(Claims claims)` Sets the JWT payload to be a JSON Claims instance.
`JwtBuilder`	`setClaims(Map<String,?> claims)` Sets the JWT payload to be a JSON Claims instance populated by the specified name/value pairs.
`JwtBuilder`	`setExpiration(Date exp)` Sets the JWT Claims `exp` (expiration) value.
`JwtBuilder`	`setHeader(Header header)` Sets (and replaces) any existing header with the specified header.
`JwtBuilder`	`setHeader(Map<String,Object> header)` Sets (and replaces) any existing header with the specified header.
`JwtBuilder`	`setHeaderParam(String name, Object value)` Applies the specified name/value pair to the header.
`JwtBuilder`	`setHeaderParams(Map<String,Object> params)` Applies the specified name/value pairs to the header.
`JwtBuilder`	`setId(String jti)` Sets the JWT Claims `jti` (JWT ID) value.
`JwtBuilder`	`setIssuedAt(Date iat)` Sets the JWT Claims `iat` (issued at) value.
`JwtBuilder`	`setIssuer(String iss)` Sets the JWT Claims `iss` (issuer) value.
`JwtBuilder`	`setNotBefore(Date nbf)` Sets the JWT Claims `nbf` (not before) value.
`JwtBuilder`	`setPayload(String payload)` Sets the JWT's payload to be a plaintext (non-JSON) string.
`JwtBuilder`	`setSubject(String sub)` Sets the JWT Claims `sub` (subject) value.
`JwtBuilder`	`signWith(Key key)` Signs the constructed JWT with the specified key using the key's `recommended signature algorithm`, producing a JWS.
`JwtBuilder`	`signWith(Key key, SignatureAlgorithm alg)` Signs the constructed JWT with the specified key using the specified algorithm, producing a JWS.
`JwtBuilder`	`signWith(SignatureAlgorithm alg, byte[] secretKey)` Deprecated. as of 0.10.0: use `Keys`.`hmacShaKeyFor(bytes)` to obtain the `Key` and then invoke `signWith(Key)` or `signWith(Key, SignatureAlgorithm)`. This method will be removed in the 1.0 release.
`JwtBuilder`	`signWith(SignatureAlgorithm alg, Key key)` Deprecated. since 0.10.0: use `signWith(Key, SignatureAlgorithm)` instead. This method will be removed in the 1.0 release.
`JwtBuilder`	`signWith(SignatureAlgorithm alg, String base64EncodedSecretKey)` Deprecated. as of 0.10.0: use `signWith(Key)` or `signWith(Key, SignatureAlgorithm)` instead. This method will be removed in the 1.0 release.

- Method Detail
  - setHeader
```
JwtBuilder setHeader(Header header)
```
    Sets (and replaces) any existing header with the specified header. If you do not want to replace the existing header and only want to append to it, use the setHeaderParams(java.util.Map) method instead.
    
    Parameters:
    header - the header to set (and potentially replace any existing header).
    
    Returns:
    the builder for method chaining.
  - setHeader
```
JwtBuilder setHeader(Map<String,Object> header)
```
    Sets (and replaces) any existing header with the specified header. If you do not want to replace the existing header and only want to append to it, use the setHeaderParams(java.util.Map) method instead.
    
    Parameters:
    header - the header to set (and potentially replace any existing header).
    
    Returns:
    the builder for method chaining.
  - setHeaderParams
```
JwtBuilder setHeaderParams(Map<String,Object> params)
```
    Applies the specified name/value pairs to the header. If a header does not yet exist at the time this method is called, one will be created automatically before applying the name/value pairs.
    
    Parameters:
    params - the header name/value pairs to append to the header.
    
    Returns:
    the builder for method chaining.
  - setHeaderParam
```
JwtBuilder setHeaderParam(String name,
                        Object value)
```
    Applies the specified name/value pair to the header. If a header does not yet exist at the time this method is called, one will be created automatically before applying the name/value pair.
    
    Parameters:
    name - the header parameter name
    value - the header parameter value
    
    Returns:
    the builder for method chaining.
  - setPayload
```
JwtBuilder setPayload(String payload)
```
    Sets the JWT's payload to be a plaintext (non-JSON) string. If you want the JWT body to be JSON, use the setClaims(Claims) or setClaims(java.util.Map) methods instead.
    The payload and claims properties are mutually exclusive - only one of the two may be used.
    
    Parameters:
    payload - the plaintext (non-JSON) string that will be the body of the JWT.
    
    Returns:
    the builder for method chaining.
  - setClaims
```
JwtBuilder setClaims(Claims claims)
```
    Sets the JWT payload to be a JSON Claims instance. If you do not want the JWT body to be JSON and instead want it to be a plaintext string, use the setPayload(String) method instead.
    The payload and claims properties are mutually exclusive - only one of the two may be used.
    
    Parameters:
    claims - the JWT claims to be set as the JWT body.
    
    Returns:
    the builder for method chaining.
  - setClaims
```
JwtBuilder setClaims(Map<String,?> claims)
```
    Sets the JWT payload to be a JSON Claims instance populated by the specified name/value pairs. If you do not want the JWT body to be JSON and instead want it to be a plaintext string, use the setPayload(String) method instead.
    The payload* and claims* properties are mutually exclusive - only one of the two may be used.
    
    Parameters:
    claims - the JWT claims to be set as the JWT body.
    
    Returns:
    the builder for method chaining.
  - addClaims
```
JwtBuilder addClaims(Map<String,Object> claims)
```
    Adds all given name/value pairs to the JSON Claims in the payload. If a Claims instance does not yet exist at the time this method is called, one will be created automatically before applying the name/value pairs.
    The payload and claims properties are mutually exclusive - only one of the two may be used.
    
    Parameters:
    claims - the JWT claims to be added to the JWT body.
    
    Returns:
    the builder for method chaining.
    Since:
    
    0.8
  - setIssuer
```
JwtBuilder setIssuer(String iss)
```
    Sets the JWT Claims iss (issuer) value. A null value will remove the property from the Claims.
    This is a convenience method. It will first ensure a Claims instance exists as the JWT body and then set the Claims issuer field with the specified value. This allows you to write code like this:
```
 String jwt = Jwts.builder().setIssuer("Joe").compact();
 
```
    instead of this:
```
 Claims claims = Jwts.claims().setIssuer("Joe");
 String jwt = Jwts.builder().setClaims(claims).compact();
 
```
    if desired.
    Specified by:
    
    setIssuer in interface ClaimsMutator<JwtBuilder>
    
    Parameters:
    iss - the JWT iss value or null to remove the property from the Claims map.
    
    Returns:
    the builder instance for method chaining.
    Since:
    
    0.2
  - setSubject
```
JwtBuilder setSubject(String sub)
```
    Sets the JWT Claims sub (subject) value. A null value will remove the property from the Claims.
    This is a convenience method. It will first ensure a Claims instance exists as the JWT body and then set the Claims subject field with the specified value. This allows you to write code like this:
```
 String jwt = Jwts.builder().setSubject("Me").compact();
 
```
    instead of this:
```
 Claims claims = Jwts.claims().setSubject("Me");
 String jwt = Jwts.builder().setClaims(claims).compact();
 
```
    if desired.
    Specified by:
    
    setSubject in interface ClaimsMutator<JwtBuilder>
    
    Parameters:
    sub - the JWT sub value or null to remove the property from the Claims map.
    
    Returns:
    the builder instance for method chaining.
    Since:
    
    0.2
  - setAudience
```
JwtBuilder setAudience(String aud)
```
    Sets the JWT Claims aud (audience) value. A null value will remove the property from the Claims.
    This is a convenience method. It will first ensure a Claims instance exists as the JWT body and then set the Claims audience field with the specified value. This allows you to write code like this:
```
 String jwt = Jwts.builder().setAudience("You").compact();
 
```
    instead of this:
```
 Claims claims = Jwts.claims().setAudience("You");
 String jwt = Jwts.builder().setClaims(claims).compact();
 
```
    if desired.
    Specified by:
    
    setAudience in interface ClaimsMutator<JwtBuilder>
    
    Parameters:
    aud - the JWT aud value or null to remove the property from the Claims map.
    
    Returns:
    the builder instance for method chaining.
    Since:
    
    0.2
  - setExpiration
```
JwtBuilder setExpiration(Date exp)
```
    Sets the JWT Claims exp (expiration) value. A null value will remove the property from the Claims.
    A JWT obtained after this timestamp should not be used.
    
    This is a convenience method. It will first ensure a Claims instance exists as the JWT body and then set the Claims expiration field with the specified value. This allows you to write code like this:
```
 String jwt = Jwts.builder().setExpiration(new Date(System.currentTimeMillis() + 3600000)).compact();
 
```
    instead of this:
```
 Claims claims = Jwts.claims().setExpiration(new Date(System.currentTimeMillis() + 3600000));
 String jwt = Jwts.builder().setClaims(claims).compact();
 
```
    if desired.
    Specified by:
    
    setExpiration in interface ClaimsMutator<JwtBuilder>
    
    Parameters:
    exp - the JWT exp value or null to remove the property from the Claims map.
    
    Returns:
    the builder instance for method chaining.
    Since:
    
    0.2
  - setNotBefore
```
JwtBuilder setNotBefore(Date nbf)
```
    Sets the JWT Claims nbf (not before) value. A null value will remove the property from the Claims.
    A JWT obtained before this timestamp should not be used.
    
    This is a convenience method. It will first ensure a Claims instance exists as the JWT body and then set the Claims notBefore field with the specified value. This allows you to write code like this:
```
 String jwt = Jwts.builder().setNotBefore(new Date()).compact();
 
```
    instead of this:
```
 Claims claims = Jwts.claims().setNotBefore(new Date());
 String jwt = Jwts.builder().setClaims(claims).compact();
 
```
    if desired.
    Specified by:
    
    setNotBefore in interface ClaimsMutator<JwtBuilder>
    
    Parameters:
    nbf - the JWT nbf value or null to remove the property from the Claims map.
    
    Returns:
    the builder instance for method chaining.
    Since:
    
    0.2
  - setIssuedAt
```
JwtBuilder setIssuedAt(Date iat)
```
    Sets the JWT Claims iat (issued at) value. A null value will remove the property from the Claims.
    The value is the timestamp when the JWT was created.
    
    This is a convenience method. It will first ensure a Claims instance exists as the JWT body and then set the Claims issuedAt field with the specified value. This allows you to write code like this:
```
 String jwt = Jwts.builder().setIssuedAt(new Date()).compact();
 
```
    instead of this:
```
 Claims claims = Jwts.claims().setIssuedAt(new Date());
 String jwt = Jwts.builder().setClaims(claims).compact();
 
```
    if desired.
    Specified by:
    
    setIssuedAt in interface ClaimsMutator<JwtBuilder>
    
    Parameters:
    iat - the JWT iat value or null to remove the property from the Claims map.
    
    Returns:
    the builder instance for method chaining.
    Since:
    
    0.2
  - setId
```
JwtBuilder setId(String jti)
```
    Sets the JWT Claims jti (JWT ID) value. A null value will remove the property from the Claims.
    The value is a CaSe-SenSiTiVe unique identifier for the JWT. If specified, this value MUST be assigned in a manner that ensures that there is a negligible probability that the same value will be accidentally assigned to a different data object. The ID can be used to prevent the JWT from being replayed.
    
    This is a convenience method. It will first ensure a Claims instance exists as the JWT body and then set the Claims id field with the specified value. This allows you to write code like this:
```
 String jwt = Jwts.builder().setId(UUID.randomUUID().toString()).compact();
 
```
    instead of this:
```
 Claims claims = Jwts.claims().setId(UUID.randomUUID().toString());
 String jwt = Jwts.builder().setClaims(claims).compact();
 
```
    if desired.
    Specified by:
    
    setId in interface ClaimsMutator<JwtBuilder>
    
    Parameters:
    jti - the JWT jti (id) value or null to remove the property from the Claims map.
    
    Returns:
    the builder instance for method chaining.
    Since:
    
    0.2
  - claim
```
JwtBuilder claim(String name,
               Object value)
```
    Sets a custom JWT Claims parameter value. A null value will remove the property from the Claims.
    This is a convenience method. It will first ensure a Claims instance exists as the JWT body and then set the named property on the Claims instance using the Claims put method. This allows you to write code like this:
```
 String jwt = Jwts.builder().claim("aName", "aValue").compact();
 
```
    instead of this:
```
 Claims claims = Jwts.claims().put("aName", "aValue");
 String jwt = Jwts.builder().setClaims(claims).compact();
 
```
    if desired.
    Parameters:
    name - the JWT Claims property name
    value - the value to set for the specified Claims property name
    
    Returns:
    the builder instance for method chaining.
    Since:
    
    0.2
  - signWith
```
JwtBuilder signWith(Key key)
                    throws InvalidKeyException
```
    Signs the constructed JWT with the specified key using the key's recommended signature algorithm, producing a JWS. If the recommended signature algorithm isn't sufficient for your needs, consider using signWith(Key, SignatureAlgorithm) instead.
    If you are looking to invoke this method with a byte array that you are confident may be used for HMAC-SHA algorithms, consider using Keys.hmacShaKeyFor(bytes) to convert the byte array into a valid Key.
    
    Parameters:
    key - the key to use for signing
    
    Returns:
    the builder instance for method chaining.
    
    Throws:
    
    InvalidKeyException - if the Key is insufficient or explicitly disallowed by the JWT specification as described by SignatureAlgorithm.forSigningKey(Key).
    Since:
    
    0.10.0
    
    See Also:
    signWith(Key, SignatureAlgorithm)
  - signWith
```
@Deprecated
JwtBuilder signWith(SignatureAlgorithm alg,
                             byte[] secretKey)
                    throws InvalidKeyException
```
    Deprecated. as of 0.10.0: use Keys.hmacShaKeyFor(bytes) to obtain the Key and then invoke signWith(Key) or signWith(Key, SignatureAlgorithm). This method will be removed in the 1.0 release.
    
    Signs the constructed JWT using the specified algorithm with the specified key, producing a JWS.
    Deprecation Notice: Deprecated as of 0.10.0
    
    Use Keys.hmacShaKeyFor(bytes) to obtain the Key and then invoke signWith(Key) or signWith(Key, SignatureAlgorithm).
    
    This method will be removed in the 1.0 release.
    
    Parameters:
    alg - the JWS algorithm to use to digitally sign the JWT, thereby producing a JWS.
    secretKey - the algorithm-specific signing key to use to digitally sign the JWT.
    
    Returns:
    the builder for method chaining.
    
    Throws:
    
    InvalidKeyException - if the Key is insufficient or explicitly disallowed by the JWT specification as described by SignatureAlgorithm.forSigningKey(Key).
  - signWith
```
@Deprecated
JwtBuilder signWith(SignatureAlgorithm alg,
                             String base64EncodedSecretKey)
                    throws InvalidKeyException
```
    Deprecated. as of 0.10.0: use signWith(Key) or signWith(Key, SignatureAlgorithm) instead. This method will be removed in the 1.0 release.
    Signs the constructed JWT using the specified algorithm with the specified key, producing a JWS.
    This is a convenience method: the string argument is first BASE64-decoded to a byte array and this resulting byte array is used to invoke signWith(SignatureAlgorithm, byte[]).
    
    Deprecation Notice: Deprecated as of 0.10.0, will be removed in the 1.0 release.
    
    This method has been deprecated because the key argument for this method can be confusing: keys for cryptographic operations are always binary (byte arrays), and many people were confused as to how bytes were obtained from the String argument.
    
    This method always expected a String argument that was effectively the same as the result of the following (pseudocode):
    
    String base64EncodedSecretKey = base64Encode(secretKeyBytes);
    
    However, a non-trivial number of JJWT users were confused by the method signature and attempted to use raw password strings as the key argument - for example signWith(HS256, myPassword) - which is almost always incorrect for cryptographic hashes and can produce erroneous or insecure results.
    
    See this StackOverflow answer explaining why raw (non-base64-encoded) strings are almost always incorrect for signature operations.
    
    To perform the correct logic with base64EncodedSecretKey strings with JJWT >= 0.10.0, you may do this:
```
 byte[] keyBytes = Decoders.BASE64.decode(base64EncodedSecretKey);
 Key key = Keys.hmacShaKeyFor(keyBytes);
 jwtBuilder.signWith(key); //or signWith(Key, SignatureAlgorithm)
 
```
    This method will be removed in the 1.0 release.
    Parameters:
    alg - the JWS algorithm to use to digitally sign the JWT, thereby producing a JWS.
    base64EncodedSecretKey - the BASE64-encoded algorithm-specific signing key to use to digitally sign the JWT.
    
    Returns:
    the builder for method chaining.
    
    Throws:
    
    InvalidKeyException - if the Key is insufficient or explicitly disallowed by the JWT specification as described by SignatureAlgorithm.forSigningKey(Key).
  - signWith
```
@Deprecated
JwtBuilder signWith(SignatureAlgorithm alg,
                             Key key)
                    throws InvalidKeyException
```
    Deprecated. since 0.10.0: use signWith(Key, SignatureAlgorithm) instead. This method will be removed in the 1.0 release.
    
    Signs the constructed JWT using the specified algorithm with the specified key, producing a JWS.
    It is typically recommended to call the signWith(Key) instead for simplicity. However, this method can be useful if the recommended algorithm heuristics do not meet your needs or if you want explicit control over the signature algorithm used with the specified key.
    
    Parameters:
    alg - the JWS algorithm to use to digitally sign the JWT, thereby producing a JWS.
    key - the algorithm-specific signing key to use to digitally sign the JWT.
    
    Returns:
    the builder for method chaining.
    
    Throws:
    
    InvalidKeyException - if the Key is insufficient or explicitly disallowed by the JWT specification for the specified algorithm.
    See Also:
    signWith(Key)
  - signWith
```
JwtBuilder signWith(Key key,
                  SignatureAlgorithm alg)
                    throws InvalidKeyException
```
    Signs the constructed JWT with the specified key using the specified algorithm, producing a JWS.
    It is typically recommended to call the signWith(Key) instead for simplicity. However, this method can be useful if the recommended algorithm heuristics do not meet your needs or if you want explicit control over the signature algorithm used with the specified key.
    
    Parameters:
    key - the signing key to use to digitally sign the JWT.
    alg - the JWS algorithm to use with the key to digitally sign the JWT, thereby producing a JWS.
    
    Returns:
    the builder for method chaining.
    
    Throws:
    
    InvalidKeyException - if the Key is insufficient or explicitly disallowed by the JWT specification for the specified algorithm.
    Since:
    
    0.10.0
    
    See Also:
    signWith(Key)
  - compressWith
```
JwtBuilder compressWith(CompressionCodec codec)
```
    Compresses the JWT body using the specified CompressionCodec.
    If your compact JWTs are large, and you want to reduce their total size during network transmission, this can be useful. For example, when embedding JWTs in URLs, some browsers may not support URLs longer than a certain length. Using compression can help ensure the compact JWT fits within that length. However, NOTE:
    
    Compatibility Warning
    
    The JWT family of specifications defines compression only for JWE (Json Web Encryption) tokens. Even so, JJWT will also support compression for JWS tokens as well if you choose to use it. However, be aware that if you use compression when creating a JWS token, other libraries may not be able to parse that JWS token. When using compression for JWS tokens, be sure that that all parties accessing the JWS token support compression for JWS.
    
    Compression when creating JWE tokens however should be universally accepted for any library that supports JWE.
    
    Parameters:
    codec - implementation of the CompressionCodec to be used.
    
    Returns:
    the builder for method chaining.
    Since:
    
    0.6.0
    
    See Also:
    CompressionCodecs
  - base64UrlEncodeWith
```
JwtBuilder base64UrlEncodeWith(Encoder<byte[],String> base64UrlEncoder)
```
    Perform Base64Url encoding with the specified Encoder.
    JJWT uses a spec-compliant encoder that works on all supported JDK versions, but you may call this method to specify a different encoder if you desire.
    
    Parameters:
    base64UrlEncoder - the encoder to use when Base64Url-encoding
    
    Returns:
    the builder for method chaining.
    Since:
    
    0.10.0
  - serializeToJsonWith
```
JwtBuilder serializeToJsonWith(Serializer<Map<String,?>> serializer)
```
    Performs object-to-JSON serialization with the specified Serializer. This is used by the builder to convert JWT/JWS/JWT headers and claims Maps to JSON strings as required by the JWT specification.
    If this method is not called, JJWT will use whatever serializer it can find at runtime, checking for the presence of well-known implementations such Jackson, Gson, and org.json. If one of these is not found in the runtime classpath, an exception will be thrown when the compact() method is invoked.
    
    Parameters:
    serializer - the serializer to use when converting Map objects to JSON strings.
    
    Returns:
    the builder for method chaining.
    Since:
    
    0.10.0
  - compact
```
String compact()
```
    Actually builds the JWT and serializes it to a compact, URL-safe string according to the JWT Compact Serialization rules.
    
    Returns:
    A compact URL-safe JWT string.

Interface JwtBuilder

Method Summary

Method Detail

setHeader

setHeader

setHeaderParams

setHeaderParam

setPayload

setClaims

setClaims

addClaims

setIssuer

setSubject

setAudience

setExpiration

setNotBefore

setIssuedAt

setId

claim

signWith

signWith

Deprecation Notice: Deprecated as of 0.10.0

signWith

Deprecation Notice: Deprecated as of 0.10.0, will be removed in the 1.0 release.

signWith

signWith

compressWith

Compatibility Warning

base64UrlEncodeWith

serializeToJsonWith

compact