Configure Data Masking

The data-mask plugin sanitizes request data that is recorded in access logs and logger plugin output. It lets you strip or redact sensitive values from query parameters, request headers, and request bodies so that personally identifiable information (PII), credentials, and other regulated data do not land in your log pipelines.

Use this guide for common masking workflows. For the full plugin field reference, supported combinations, and additional examples, see data-mask.

note

data-mask runs in the gateway log phase. It changes what loggers and access logs see, but it does not change what the upstream service receives or what the client gets back.

Prerequisites

• An API7 Enterprise instance is running.
• A Gateway Group is created and a Gateway instance is running.
• A token from the Dashboard.

Configure Data Masking

The following example masks sensitive fields in a URL-encoded request body and writes the masked request body to a local log file with file-logger.

Step 1: Create a Published Service with an Upstream

Admin API

curl -k "https://localhost:7443/apisix/admin/services/data-mask-httpbin-service?gateway_group_id={group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "data-mask-httpbin-service",
    "upstream": {
      "type": "roundrobin",
      "scheme": "http",
      "nodes": [
        {
          "host": "httpbin.org",
          "port": 80,
          "weight": 100
        }
      ]
    }
  }'

ADC

adc.yaml

services:
  - name: data-mask-httpbin-service
    upstream:
      name: default
      scheme: http
      nodes:
        - host: httpbin.org
          port: 80
          weight: 100
    routes:
      - name: data-mask-route
        uris:
          - /anything/data-mask
        methods:
          - POST
        plugins:
          data-mask:
            request:
              - action: remove
                body_format: urlencoded
                name: password
                type: body
              - action: replace
                body_format: urlencoded
                name: token
                type: body
                value: "*****"
              - action: regex
                body_format: urlencoded
                name: card
                regex: "(\\d+)\\-\\d+\\-\\d+\\-(\\d+)"
                type: body
                value: "$1-****-****-$2"
          file-logger:
            include_req_body: true
            path: /tmp/mask-urlencoded-body.log

adc sync -f adc.yaml

Step 2: Create a Route and Enable data-mask

Create a route that enables both data-mask and file-logger.

Admin API

curl -k "https://localhost:7443/apisix/admin/routes/data-mask-route?gateway_group_id={group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "data-mask-route",
    "paths": ["/anything/data-mask"],
    "methods": ["POST"],
    "service_id": "data-mask-httpbin-service",
    "plugins": {
      "data-mask": {
        "request": [
          {
            "type": "body",
            "body_format": "urlencoded",
            "name": "password",
            "action": "remove"
          },
          {
            "type": "body",
            "body_format": "urlencoded",
            "name": "token",
            "action": "replace",
            "value": "*****"
          },
          {
            "type": "body",
            "body_format": "urlencoded",
            "name": "card",
            "action": "regex",
            "regex": "(\\d+)\\-\\d+\\-\\d+\\-(\\d+)",
            "value": "$1-****-****-$2"
          }
        ]
      },
      "file-logger": {
        "include_req_body": true,
        "path": "/tmp/mask-urlencoded-body.log"
      }
    }
  }'

ADC

The route is already included in the previous adc.yaml example.

Validate the Configuration

Send a request to the route:

curl -i "http://127.0.0.1:9080/anything/data-mask" \
  --data-urlencode "password=abc" \
  --data-urlencode "token=xyz" \
  --data-urlencode "card=1234-1234-1234-1234"

You should receive 200 OK. The upstream still receives the original values.

Then inspect the gateway log file. If you are running the gateway in Docker, first find the container name:

docker ps --format '{{.Names}}'

Then read the log file from the gateway container:

docker exec <gateway-container-name> sh -lc 'cat /tmp/mask-urlencoded-body.log'

You should see a masked log entry similar to the following:

{
  "request": {
    "uri": "/anything/data-mask",
    "body": "token=*****&card=1234-****-****-1234",
    "method": "POST",
    "url": "http://127.0.0.1:9080/anything/data-mask"
  }
}

The password field is removed, token is replaced, and the middle digits of card are masked in the log output. If the route returns 404 immediately after you apply the configuration, wait a few seconds for the latest configuration to reach the gateway and retry.

Next Steps

• Configure Logging - attach other logger plugins to capture masked request data.
• Rate Limiting - protect APIs from abuse.
• Secure Credentials - protect sensitive configuration data.