JWT Step
The JWT step generates or validates JSON Web Tokens (JWT) during test execution. Use it to authenticate subsequent requests with a freshly signed token, or to verify a token's signature, lifetime, and claims.
When to Use
- Generating a signed JWT to authenticate a subsequent request
- Testing APIs that accept custom or service-issued JWTs
- Validating a token's structure, signature, and claims in a response
Quickest Scenario (Generate)
- Add a JWT step from the palette.
- Set Action to Generation.
- Choose a Signing Algorithm (e.g.
HS256) and provide a Signing Key (symmetric secret). - Edit the Payload Claims (the default
iss,sub,aud,exp,nbf,iat,jtiare pre-filled). - Run the test — the generated token is written to the Token box and stored in
JwtSecurityTokenString.
Modes
The Action combo selects the mode:
- Generation — creates a signed JWT from the configured payload and algorithm.
- Validation — verifies a supplied token's signature, lifetime, and claim assertions.
Generation Mode
| Field | Description |
|---|---|
| Signing Algorithm | One of HS256, HS384, HS512, RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512. |
| Signing Key | The key/secret used to sign. Symmetric algorithms use a clear-text, Base64, Base64URL, or hex secret; asymmetric algorithms use a PFX/P12 file, PEM file, X.509 store, JWK, or credential profile. |
| Payload Claims | The token claims. Well-known claims auto-populate sensible defaults and a value type. |
| Token | Read-only output of the generated JWT (also JwtSecurityTokenString). |
The payload editor exposes, per claim: Name, Value, Type, and Description. Supported claim value types are String, Numeric, Decimal, Boolean, and Timestamp (Unix epoch seconds, shown formatted). Well-known timestamp claims (exp, nbf, iat, …) display a human-readable date.
Validation Mode
| Field | Description |
|---|---|
| Verification Key / Secret | The key used to verify the signature (same source types as Generation). The algorithm is auto-detected from the token header. |
| Token | The JWT to validate (input). Supports variabilization, e.g. ${authToken}. |
| Valid Issuer | If set, the iss claim is validated against this value. Leave empty to skip issuer validation. |
| Valid Audience | If set, the aud claim is validated against this value. Leave empty to skip audience validation. |
| Validate Lifetime | When true (default), the exp and nbf claims are validated. Set to false only for debugging. |
| Claim Assertions | Optional per-claim checks executed during validation. |
Claim Assertions
Each assertion has:
| Column | Description |
|---|---|
| Name | The claim to check (e.g. sub, role, scope). Auto-completes from well-known claim names. |
| Operator | Equals (exact, case-sensitive), Contains (substring), or Regex (regular expression). |
| Value | The expected value. Supports variabilization. |
If any assertion fails, the validation step reports a failure.
Example: OAuth2 + JWT Pattern
Step 1: OAuth2 Authentication → stores the token in the variable AccessToken
Step 2: JWT (Validate) → Token = ${AccessToken}, verify exp via Validate Lifetime
Step 3: Send Request → Header: Authorization = Bearer ${AccessToken}
AccessToken in the OAuth2 step is the variable's name, written bare; where a field takes a value,
reference it as ${AccessToken}. Note that the OAuth2 step's own fields resolve ${…} against the
active environment's variables only — a token captured into the case or suite scope is not visible
there.
In Generation mode the Token box is read-only — the value is produced when the step runs. In Validation mode, paste or variabilize the token there.
Why
JWT generation lets you exercise authenticated endpoints with tokens you control, while validation lets you assert that a system-under-test issues well-formed, correctly signed tokens with the expected claims.