Jwt

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

Parameters

Return value

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

Verifies a JWT signature and validates standard claims.

Parameters

Return value

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);
}

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

Parameters

Return value

// 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);

// Example HS256 Key Object structure:
var key = Jwt.Key.fromSecret("mySecret", { kid: "key1" });
// Returns: { kty: "oct", alg: "HS256", use: "sig", secret: "mySecret", kid: "key1" }

// Example ES256 Key Object structure:
var key = Jwt.Key.fromEcRaw({
    privateKey: privateKeyBytes,  // Uint8Array, 32 bytes
    publicKey: publicKeyBytes,    // Uint8Array, 65 bytes
    kid: "ec-key-1"
});
// Returns: { kty: "EC", alg: "ES256", use: "sig", privateKey: ..., publicKey: ..., kid: "ec-key-1" }

// Key with only public part (for verification):
var pubKey = Jwt.Key.fromEcRaw({ publicKey: publicKeyBytes });
// Returns: { kty: "EC", alg: "ES256", use: "sig", privateKey: null, publicKey: ..., kid: undefined }

Creates a key object for symmetric algorithms (HS256).

Parameters

Return value

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

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

Parameters

Return value

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("...") 
});

Creates an ES256 EC key object from a PEM-encoded key.

Parameters

Return value

Remarks

The PEM parser supports standard PKCS#8 (PrivateKeyInfo) and RFC 5915 (ECPrivateKey) formats for EC P-256 keys, as well as SubjectPublicKeyInfo for public keys. The implementation relies on Encoding.base64ToBin being available. If both private and public key material are present in the PEM, both will be extracted.

var pem = "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----";
var key = Jwt.Key.fromPem(pem, { kid: "ec1" });
var payload = Jwt.verify(token, {
    key: key,
    algorithms: ["ES256"]
});

Exports an EC (ES256) key object to a standard PEM-encoded string.

Parameters

Return value

Remarks

The output format is a private key with embedded public key, the resulting PEM uses the PKCS#8 format wrapping an RFC 5915 structure.

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

var pem = Jwt.Key.toPem(key);
// pem can now be stored or transported and later re-imported with Jwt.Key.fromPem()

Exports only the public part of an EC key object to a PEM-encoded string.

Parameters

Return value

// Example: Generate a key pair and export to separate PEM files
try {
    var ecdsa = Crypto.ecdsa("ES256", null, null);
    var privateKeyRaw = ecdsa.private(true); // true for Uint8Array output
    var publicKeyRaw = ecdsa.public(true);

    var keyPair = Jwt.Key.fromEcRaw({
        privateKey: privateKeyRaw,
        publicKey: publicKeyRaw,
        kid: "my-app-jwt-key"
    });

    var publicKeyPem = Jwt.Key.toPemPublic(keyPair);
    // Store or transmit publicKeyPem for token verification
} catch (error) {
    log("PEM conversion error: " + error.message);
} finally {
    ecdsa.close();
}

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