By Abhinav Thodishetty · Updated 22 October 2026.
IBM DataPower JSON Web Actions: JWE, JWS and API Message Security
TLS protects a connection. JWE and JWS can protect the message itself. The real architecture decision is knowing which protection is required, where it belongs, and who owns the keys.
A sensitive API request can move through several systems before it reaches its final destination. HTTPS protects each network connection, but once TLS terminates at a gateway or intermediary, the payload may be visible inside that trust zone.
IBM DataPower Gateway supports JSON Web Encryption (JWE) and JSON Web Signature (JWS) actions that can add message-level protection inside a processing policy. The important question is not simply whether encryption or signing is available. It is deciding who may read the message, who must be able to verify it, and where DataPower sits in that trust model.
The core design question:
Which parties are allowed to read the payload, and which party must be able to prove that the message has not been altered?
JWE and JWS in one simple model
JWE is a locked envelope. It protects message confidentiality so that only a party with the required decryption capability can recover the protected content.
JWS is a tamper-evident seal. It allows a receiver to validate the signed content and determine whether it has changed. Depending on the key and trust model, it can also support authentication of the signer.
They solve different problems and can also be used together. A signature does not hide the payload, and encryption by itself should not be treated as proof that the sender is authorized.
| Question | JWE | JWS |
|---|---|---|
| Primary purpose | Confidentiality and integrity of encrypted content | Integrity and signature/MAC validation |
| Can an intermediary read the payload? | Not without the required decryption capability | Usually yes; signing alone does not hide content |
| Main design question | Who is allowed to read this message? | Who produced this message, and has it changed? |
How this fits into a DataPower API flow
JSON Web Actions sit inside a wider DataPower policy that may also perform authentication, authorization, validation, routing and other API controls.
An inbound message may be verified with JWS before DataPower accepts it as trusted input. A JWE payload may need to be decrypted if the gateway must inspect the content for schema validation, routing or policy decisions. On the outbound side, DataPower can sign or encrypt the message for the next recipient when the security contract requires it.
Important: If the gateway must inspect plaintext, the message cannot remain opaque to DataPower throughout processing. The order of decrypt, validate, process, sign, and encrypt must match the trust model.
JWE, JWS, and TLS solve different problems
| Control | What it protects | What it does not replace |
|---|---|---|
| TLS | Data in transit on a network connection | Message-level protection after TLS terminates |
| JWS | Message integrity and signature validation | Payload confidentiality or business authorization |
| JWE | Message confidentiality | Authorization or independent signer verification |
| JWE + JWS | Confidentiality plus signed-message assurance | Key governance, authorization and replay protection |
The difficult part: key ownership
The cryptographic action is only one part of the solution. Production success depends heavily on how keys are governed. Teams should agree on who generates, approves, stores, distributes, rotates, and revokes key material before the API depends on it.
- Define approved algorithms and key types.
- Use controlled key identifiers.
- Plan rotation and rollback before production.
- Restrict access to private keys and shared secrets.
- Avoid logging plaintext, keys, or sensitive headers.
What JWE and JWS do not solve
- Authorization: a valid signature does not automatically mean the caller may perform the requested operation.
- Replay protection: timestamps, nonces, unique request IDs, or duplicate detection may still be required.
- Transport security: TLS remains important even when JWE or JWS is used.
- Operational security: key access, rotation, monitoring, and incident response still matter.
Production considerations
Test the full path with representative payload sizes and traffic volumes. Cryptographic processing adds CPU cost, message overhead, and new failure modes, so latency and throughput should be measured rather than assumed.
Negative-path testing is equally important. Invalid signatures, wrong recipient keys, unsupported algorithms, malformed protected messages, and failed decryptions should be rejected without accidentally routing an unprotected request to the backend.
A good implementation is predictable when protection fails.
Failure handling should be as deliberately designed as the success path.
Frequently asked questions
Does JWS encrypt the payload?
No. JWS protects integrity and supports signature or MAC verification. Use JWE when the payload itself must remain confidential.
Does JWE prove who sent the message?
Not by itself. If the receiver must verify the signer, use an appropriate signing and trust-validation design as well.
Do JWE and JWS replace TLS?
No. TLS protects the network connection, while JWE and JWS protect the message under their respective security models. They can be used together.
The takeaway
JWE and JWS are most useful when they implement a clearly defined security contract. Start by deciding who may read the message, who must verify it, and where plaintext is allowed to exist. Then place the DataPower JSON Web Actions around those boundaries.
The cryptography matters, but the real production architecture is built around trust, key ownership, policy order, failure handling and operational control.
