Payload Filters
Control which fields are returned in upstream JSON responses before they reach the caller
Payload Filters
Payload Filters allow you to retain or destroy fields in upstream JSON responses before they are returned to the caller. They operate on the response body after a successful target call and are applied in a sequential four-stage pipeline across the four entity scopes.
Filters only apply to 2xx JSON responses. If filters are configured but the upstream returns a non-JSON response, a 422 error is returned rather than passing through unfiltered data.
How filters work
The four-stage pipeline
Filters are applied in a fixed sequential order across four scopes. Each stage's output becomes the input for the next stage — meaning a field removed in an earlier stage is gone for all subsequent stages and cannot be restored.
| Stage | Scope | Authority |
|---|---|---|
| 1 | Target Credential | Highest — upstream access rights imposed by the credential used to call the target |
| 2 | Target | Platform-wide policy for all proxies using this target |
| 3 | Proxy Credential | Consumer entitlements — restricts what a specific caller may see |
| 4 | Proxy | Lowest — operational proxy behaviour |
Earlier stages have final authority. A field destroyed in Stage 1 cannot be restored by any later stage. Design your filters with this in mind — place your most fundamental data restrictions in the earliest applicable scope.
Why this order?
The pipeline is ordered from the data source side (what the upstream allows) to the consumer side (what the caller is permitted to receive):
- Stage 1 (Target Credential) — The target credential represents the authentication used to call the upstream API. If that credential has restricted access to certain data (e.g. a read-only or limited-scope API key), those upstream restrictions are the most foundational constraint and must be applied first.
- Stage 2 (Target) — Target-level filters apply to every proxy that uses this target, establishing a platform-wide data policy for that upstream service before any consumer-facing configuration is considered.
- Stage 3 (Proxy Credential) — The proxy credential identifies the specific consumer calling into RequestRocket. A consumer's entitlements sit above the proxy configuration — the proxy cannot grant a consumer access to data that their credential restricts.
- Stage 4 (Proxy) — The proxy is the most operationally specific unit. It can further refine what passes through, but it cannot override restrictions established by the upstream or the consumer's credential.
Within a single stage
Within each stage, filter records are evaluated by their priority (higher number = evaluated first). Each filter record can match based on the request and response context, and contains one or more field-level operations.
Effect resolution per field:
If multiple operations target the same field with conflicting effects, destroy beats retain. A field that any operation marks for destruction will be removed, even if other operations would retain it.
Filter operations
Each filter record defines one or more operations. An operation specifies:
| Property | Description |
|---|---|
| Field path | JSON path to the field (e.g. user.email, items[*].price) |
| Effect | retain or destroy |
| Priority | Order in which operations are evaluated within the record |
| Conditions | Optional request/response conditions that must match for the record to apply |
Retain vs Destroy
- Retain — Keep this field in the response. All other fields not explicitly retained may be removed depending on the default filter operation configured on the record.
- Destroy — Remove this field from the response, regardless of any retain operations.
Destroy always beats retain. If a field is targeted by both a destroy and a retain operation (within the same stage or across operations on the same record), it will be destroyed.
Where to configure filters
| Where | Scope |
|---|---|
| Proxies → [Proxy] → Edit → Payload Filters | Stage 4 — that proxy only |
| Proxy Credentials → [Credential] → Payload Filters | Stage 3 — all proxies using that credential |
| Target Credentials → [Credential] → Payload Filters | Stage 1 — all proxies using that target credential |
| Targets → [Target] → Payload Filters | Stage 2 — all requests to that target |
Changes to filters take effect immediately. No separate save or publish is required. Deletion of filter records is permanent. Consider testing in a non-production environment first.
Examples
Remove a sensitive field globally (Target Credential)
Configure a destroy operation on the target credential for user.passwordHash. This ensures the field is never returned to any proxy or caller using that credential, regardless of what downstream filters do.
Strip PII from all responses for a target (Target)
Configure destroy operations on the target for fields like user.email, user.phone, and user.address. Every proxy pointing at this target will have these fields removed before consumer-side filters are applied.
Restrict a consumer to specific fields (Proxy Credential)
Configure a retain operation on the proxy credential for only the fields the consumer needs (e.g. id, name, status). All other fields will be removed for any proxy that consumer uses.
Expose an additional field for a specific integration (Proxy)
Configure a retain operation on a specific proxy for a field that the proxy credential would otherwise remove. However, note that if an earlier stage (target credential or target) has already destroyed that field, the proxy retain operation has no effect.
Troubleshooting
Fields missing from response unexpectedly
- Check all four stages — a destroy in any earlier stage removes the field permanently.
- Work through the pipeline in order: target credential → target → proxy credential → proxy.
- Verify which entity has the filter configured and its effect.
Filter not being applied
- Confirm the filter record is saved and appears in the filters list.
- Check that the response from the upstream is valid JSON (filters only apply to JSON responses).
- Verify the filter record's matching conditions — if conditions are configured, the request/response must satisfy all of them.
Unexpected 422 response
This occurs when filters are configured but the upstream returns a non-JSON response. Either remove the filter, or ensure your proxy is calling a JSON-returning endpoint.
Relationship with rules
Filters and rules are independent mechanisms applied at different points in the request lifecycle:
- Rules are evaluated on the incoming request before it is forwarded to the target. All four scopes must allow the request.
- Filters are applied to the outgoing response after a successful target call, in the fixed four-stage pipeline.
A request can pass all rules and still have its response filtered. A request denied by rules never reaches the filter stage.