GetJWTByKeyName()

Creates a JSON Web Token (JWT) for a JSON payload. This function uses a key that’s stored using a key stored in Key Management.

JWTs offer a method of securely transmitting information between parties as a JSON object. The information is digitally signed using cryptographic algorithms. Because the JWT is signed, parties that receive a JWT can be assured that the data wasn’t tampered with in transit. Marketing Cloud Engagement supports hash-based message authentication code (HMAC) and Rivest–Shamir–Adleman public-key signatures (RSA signatures).

We recommend that you use GetJWTByKeyName() instead of its companion function GetJWT(). The difference between GetJWTByKeyName() and GetJWT() is the first parameter. In the GetJWT() function, you pass your secret as the first parameter in plain text. With GetJWTByKeyName(), you pass a reference to a key that’s stored using the Key Management feature of Marketing Cloud Engagement. With Key Management, you can also control which users have access to your keys. These factors make the GetJWTByKeyName() function more secure for most use cases.

The GetJWTByKeyName() function uses this syntax: GetJWTByKeyName({keyName}, {algorithm}, {jsonPayload})

The function has the parameters listed in this table.

Name	Type	Description
keyName	String	Required. The external key of a key that’s stored using Key Management. The function converts the key string to a byte array using UTF-8. It supports Base 16, Base 64, and ASCII character strings.
algorithm	String	Required. A string that indicates which cryptographic algorithm and hash function to use in the token. Possible values: HS256—HMAC secret with SHA-256 hash HS384—HMAC secret with SHA-384 hash HS512—HMAC secret with SHA-512 hash RS256—RSA signature with SHA-256 hash RS384—RSA signature with SHA-384 hash RS512—RSA signature with SHA-512 hash
jsonPayload	String	Required. The payload of the JWT. Typically, the payload is a JSON object with name-value pairs. The JWT payload isn’t encrypted.

To use the function, specify the external key of the key to use to sign the token. Next, specify the encoding algorithm. Lastly, provide the payload that you want to encode.

The function outputs a JWT.

If the syntax for the function is invalid, the function returns an InvalidFunctionException error. This error can occur if you call the function without providing the right number of parameters or if you provide an invalid data type for a parameter.

If the function call contains invalid data, it returns a FunctionExecutionException error. This error can occur if one of the parameter values is invalid. For example, the error is returned when the syntax of the JSON payload is incorrect.