Jwt

This document describes the Jwt library available in the JavaScript environment for app services. It provides functionality for handling JSON Web Tokens (JWT) and JSON Web Signatures (JWS), including signing, verifying, and decoding.

Table of content

Object	Jwt
Functions	sign verify decode
Object	Jwt.Key
Functions	fromSecret fromEcRaw
Reference	Error Codes

Jwt

sign

Generates a signed JWT string using the specified payload and key.

Parameters

object payload	The JSON object to be signed as the token payload.
object options	An object containing configuration for the signing process. key (Required): The key to use for signing. Can be a Key object created via Jwt.Key or a raw key. alg (Optional): The algorithm to use. Supported values are "ES256" (default) and "HS256". header (Optional): An object containing additional header fields to be merged with the default header.

Return value

string

The compact JWT string (header.payload.signature).

var key = Jwt.Key.fromSecret("mySuperSecret", { kid: "key1" });
var token = Jwt.sign({ sub: "user123", role: "admin" }, { key: key, alg: "HS256" });

verify

Verifies a JWT signature and validates standard claims.

Parameters

string token

The JWT string to verify.

object options

Required. An object containing verification parameters.
key (Required): The key used to verify the signature. Can be a Key object or a raw key (public key for ES256, secret for HS256).
algorithms (Optional): An array of strings specifying allowed algorithms (e.g. ["ES256", "HS256"]). If provided, the token's algorithm must be in this list.
issuer (Optional): A string or array of strings. If provided, checks if the "iss" claim matches one of the values.
audience (Optional): A string or array of strings. If provided, checks if the "aud" claim matches (supports intersection of arrays).
subject (Optional): A string. If provided, checks if the "sub" claim matches exactly.
clockTolerance (Optional): Number of seconds to tolerate when checking "exp" and "nbf" claims. Defaults to 0.

Return value

object

The decoded payload object if verification is successful.

Remarks

This function validates exp (Expiration), nbf (Not Before), iss (Issuer), aud (Audience), and sub (Subject) if the corresponding options are provided. See Error Codes for failure conditions.

try {
    var payload = Jwt.verify(token, { 
        key: publicKey, 
        algorithms: ["ES256"],
        issuer: "my-auth-server",
        audience: "my-app"
    });
    log("Verified user: " + payload.sub);
} catch (e) {
    log("Verification failed: code=" + e.code + " message=" + e.message);
}

decode

Decodes a JWT without verifying the signature. Use with caution.

Parameters

string token	The JWT string to decode.
object options	Optional configuration. complete (Optional): If true, returns an object containing the header, payload, and signature. If false (default), returns only the payload.

Return value

object

The payload object (default) or the complete token structure.

// Get just the payload
var payload = Jwt.decode(token);

// Get the full structure
var decoded = Jwt.decode(token, { complete: true });
log("Algorithm used: " + decoded.header.alg);

Jwt.Key

Helper object to create standardized key structures for use with Jwt functions.

fromSecret

Creates a key object for symmetric algorithms (HS256).

Parameters

string/Uint8Array secret	The shared secret.
object opts	Optional parameters. kid (Optional): Key ID to associate with this key.

Return value

object

A Key object configured for HS256.

var hmacKey = Jwt.Key.fromSecret("secretPassword", { kid: "k1" });

fromEcRaw

Creates a key object for Elliptic Curve algorithms (ES256).

Parameters

object opts

Configuration object.
privateKey (Optional): The private key. Uint8Array is preferred, but hex strings are accepted.
publicKey (Optional): The public key. Uint8Array is preferred, but hex strings are accepted.
kid (Optional): Key ID to associate with this key.

Return value

object

A Key object configured for ES256.

Remarks

While this function accepts hex strings, it is recommended to use Encoding.hexToBin() to pass explicit Uint8Arrays, as this avoids ambiguity and matches the underlying Crypto library expectations.

var ecKey = Jwt.Key.fromEcRaw({
    privateKey: Encoding.hexToBin("..."), 
    publicKey: Encoding.hexToBin("...") 
});

Error Codes

When an error occurs, the Error object thrown will contain a code property with one of the following values:

malformed_token	The token string is not a valid JWT (wrong number of parts, invalid Base64, or invalid JSON).
key_required	The `options` object or the `key` property is missing.
key_error	The provided key is invalid or missing a required component (e.g. missing privateKey for signing).
alg_mismatch	The key algorithm does not match the requested algorithm.
unsupported_algorithm	The algorithm is not supported or not permitted by the `algorithms` option.
signature_invalid	The signature verification failed.
token_expired	The current time is past the "exp" claim (plus clock tolerance).
token_not_yet_valid	The current time is before the "nbf" claim (minus clock tolerance).
issuer_invalid	The "iss" claim does not match the expected issuer.
audience_invalid	The "aud" claim does not match the expected audience.
subject_invalid	The "sub" claim does not match the expected subject.