You're viewing **Apigee Edge** documentation.  
[Go to the
**Apigee X** documentation](http://cloud.google.com/apigee/docs/api-platform/security/data-masking). info

When you debug APIs calls in Edge, the content can sometimes contain sensitive data, such
credit cards or personally identifiable health information (PHI) that needs to be masked.

Edge provides different ways of hiding or masking sensitive data from
[Trace](https://docs.apigee.com/api-platform/debug/using-trace-tool-0) and debug sessions.

## Hiding sensitive data

You can prevent sensitive data from appearing in the Trace tool and debug sessions by creating
custom variables prefixed with "`private.`".

For example, when using the Key Value Map Operations policy to retrieve values from an
encrypted key value map, format the variable names as follows to ensure the values don't appear
in Trace or debug sessions:

```
<Get assignTo="private.hiddenData">
```

Hiding sensitive variables is an alternative to using data masking, described next. The
difference between hiding and masking is that hidden variables don't appear at all, and masked
values are replaced with asterisks in Trace and debug sessions.

Variables without the "`private.`" prefix are displayed in clear text in Trace and
debug sessions even if the data comes from an encrypted data store such as an encrypted key value
map. Use masking (below) if you want to mask these values.

## Masking sensitive data

Edge lets you define 'mask configurations' to mask specific data in trace and debug sessions.
Masking configurations can be set globally (at the organization-level) or locally (at the API
proxy level).

When data is masked, it is replaced with asterisks in the trace output. For example:

```
<description>**********</description>
```

> [!WARNING]
> **Warning:** Data masking is enabled only when a trace session or debug session is enabled for an API proxy. If no trace or debug sessions are enabled on an API proxy, the data will not be masked. If you change your data masking configuration, you must stop and restart the tracing session to see the effect of your changes.

### Using Mask Configurations

Mask configurations enable you to identify sensitive data in these sources:

- **XML payloads:** Using XPath, you identify XML elements to be filtered from request or response message payloads.
- **JSON payloads:** Using JSONPath, you identify JSON properties to be filtered from request or response message payloads.
- **Flow variables:** You can specify a list of variables that should be masked in debug output. When you specify the `request.content`, `response.content`, or `message.content` flow variables, the request/response body is also masked.

The basic structure of a mask configuration is shown by the following XML representation:

> [!NOTE]
> **Note:** The name of the mask must be code\>default.

```
<MaskDataConfiguration name="default">
    <Namespaces>
        <Namespace prefix="myco">http://example.com</Namespace>
    </Namespaces>
    <XPathsRequest>
        <XPathRequest>/myco:Greeting/myco:User</XPathRequest>
    </XPathsRequest>
    <XPathsResponse>
        <XPathResponse>/myco:Greeting/myco:User</XPathResponse>
    </XPathsResponse>
    <JSONPathsRequest>
        <JSONPathRequest>$.store.book[*].author</JSONPathRequest>
    </JSONPathsRequest>
    <JSONPathsResponse>
        <JSONPathResponse>$.store.book[*].author</JSONPathResponse>
    </JSONPathsResponse>
    <XPathsFault>
        <XPathFault>/myco:Greeting/myco:User</XPathFault>
    </XPathsFault>
    <JSONPathsFault>
        <JSONPathFault>$.store.book[*].author</JSONPathFault>
    </JSONPathsFault>
    <Variables>
        <Variable>request.header.user-agent</Variable>
        <Variable>request.formparam.password</Variable>
    </Variables>
</MaskDataConfiguration>
```

### Configuring a mask
configuration resource

Define a mask configuration using the following elements.

> [!IMPORTANT]
> **Tip:** If you use ServiceCallout to make a request, the information in that request is not masked with the normal mask configuration. If you wish to mask ServiceCallout request information, add the flow variable `ServiceCallout.request` to the `<Variables>` element of the `<MaskDataConfiguration>` configuration.

| Field Name | Description | Default | Required? |
|---|---|---|---|
| XPathsRequest | A list of XPath expressions that will be evaluated against XML payloads (if any) in the request path. Any XPaths that successfully resolve will result in the value of the XML element being masked. | N/A | No |
| XPathsResponse | A list of XPath expressions that will be evaluated against XML payloads (if any) in the response path. Any XPaths that successfully resolve will result in the value of the XML element being masked. | N/A | No |
| JSONPathsRequest | A list of JSONPath expressions that will be evaluated against JSON payloads (if any) in the request path. Any JSONPaths that successfully resolve will result in the value of the JSON property being masked. | N/A | No |
| JSONPathsResponse | A list of JSONPath expressions that will be evaluated against JSON payloads (if any) in the response path. Any JSONPaths that successfully resolve will result in the value of the JSON property being masked. | N/A | No |
| XPathsFault | A list of XPath expressions that will be evaluated against XML payloads (if any) in the error flow (which executes if a fault is thrown at any point in the flow). Any XPaths that successfully resolve will result in the value of the XML element being masked. | N/A | No |
| JSONPathsFault | A list of JSON expressions that will be evaluated against JSON payloads (if any) in the error flow (which executes if a fault is thrown at any point in the flow). Any JSONPaths that successfully resolve will result in the value of the JSON property being masked. | N/A | No |
| Variables | A list of variables (either pre-defined or custom) whose values will be masked. For a list of default variables, see [Variables reference](https://docs.apigee.com/api-platform/reference/variables-reference). > [!NOTE] > **Note:** When you specify the `request.content`, `response.content`, or `message.content` flow variables, the request/response body is also masked. | N/A | No |

### Mask configuration API

Mask configurations are defined as XML- or JSON-formatted files that you upload and download
using the RESTful management API. For a complete list of data masking APIs, see [Data Masks](https://docs.apigee.com/api-reference/content/data-masks).

To see existing mask configurations, you can simply call the API resource
`/maskconfigs` in your organization:

```
$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/maskconfigs \
-u email
```

This example shows [Basic](https://docs.apigee.com/api-platform/system-administration/basic-auth) syntax
for authentication. You may be able to use other types of authentication, such as
[Oauth2](https://docs.apigee.com/api-platform/system-administration/using-oauth2) or
[SAML](https://docs.apigee.com/api-platform/system-administration/enabling-saml-authentication-edge).

To see mask configurations defined for specific API proxies, you can call the
`/maskconfigs` API:

```
$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/apis/{api_name}/maskconfigs \
-u email
```

To see a specific mask configuration, specify the name of the mask:

```
$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/maskconfigs/default \
-u email
```

```
$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/apis/{api_name}/maskconfigs/default \
-u email
```

To create a mask configuration, use the POST verb to submit a payload that defines the mask
configuration:

```
$ curl -H "Content-type:text/xml" -X POST -d \
'<MaskDataConfiguration name="default">
    <Namespaces>
        <Namespace prefix="myco">http://example.com</Namespace>
    </Namespaces>
    <XPathsRequest>
        <XPathRequest>/myco:Greeting/myco:User</XPathRequest>
    </XPathsRequest>
    <XPathsResponse>
        <XPathResponse>/myco:Greeting/myco:User</XPathResponse>
    </XPathsResponse>
    <JSONPathsRequest>
        <JSONPathRequest>$.store.book[*].author</JSONPathRequest>
    </JSONPathsRequest>
    <JSONPathsResponse>
        <JSONPathResponse>$.store.book[*].author</JSONPathResponse>
    </JSONPathsResponse>
    <XPathsFault>
        <XPathFault>/myco:Greeting/myco:User</XPathFault>
    </XPathsFault>
    <JSONPathsFault>
        <JSONPathFault>$.store.book[*].author</JSONPathFault>
    </JSONPathsFault>
    <Variables>
        <Variable>request.header.user-agent</Variable>
        <Variable>request.formparam.password</Variable>
    </Variables>
</MaskDataConfiguration>' \
https://api.enterprise.apigee.com/v1/o/{org_name}/maskconfigs \
-u email
```
To create a mask configuration that is scoped to a specific API proxy:

```
$ curl -H "Content-type:text/xml" -X POST -d \
'<MaskDataConfiguration name="default">
    <Namespaces>
        <Namespace prefix="myco">http://example.com</Namespace>
    </Namespaces>
    <XPathsRequest>
        <XPathRequest>/myco:Greeting/myco:User</XPathRequest>
    </XPathsRequest>
    <XPathsResponse>
        <XPathResponse>/myco:Greeting/myco:User</XPathResponse>
    </XPathsResponse>
    <JSONPathsRequest>
        <JSONPathRequest>$.store.book[*].author</JSONPathRequest>
    </JSONPathsRequest>
    <JSONPathsResponse>
        <JSONPathResponse>$.store.book[*].author</JSONPathResponse>
    </JSONPathsResponse>
    <XPathsFault>
        <XPathFault>/myco:Greeting/myco:User</XPathFault>
    </XPathsFault>
    <JSONPathsFault>
        <JSONPathFault>$.store.book[*].author</JSONPathFault>
    </JSONPathsFault>
    <Variables>
        <Variable>request.header.user-agent</Variable>
        <Variable>request.formparam.password</Variable>
    </Variables>
</MaskDataConfiguration>' \
https://api.enterprise.apigee.com/v1/o/{org_name}/apis/{api_name}/maskconfigs \
-u email
```

You can delete a mask configuration using the DELETE verb:

```
$ curl -X DELETE \
https://api.enterprise.apigee.com/v1/o/{org_name}/apis/{api_name}/maskconfigs/{maskconfig_name} \
-u email
```

This example shows [Basic](https://docs.apigee.com/api-platform/system-administration/basic-auth) syntax
for authentication. You may be able to use other types of authentication, such as
[Oauth2](https://docs.apigee.com/api-platform/system-administration/using-oauth2) or
[SAML](https://docs.apigee.com/api-platform/system-administration/enabling-saml-authentication-edge).

The response to a DELETE operation is an HTTP code `204` with no message
content.

### Masking for XML namespaces

A mask configuration doesn't require the `<Namespace>` element in an XPATH
definition unless a namespace is defined in the XML payload. This is also true if the XML payload
uses a default namespace.

For example, the XML payload does not define a namespace:

```
<employee>
    <name>abc</name>
    <age>50</age>
</employee>
```

Therefore, the mask configuration doesn't require the `<Namespace>` element:

```
<MaskDataConfiguration>
    <XPathsRequest>
        <XPathRequest>/employee/name</XPathRequest>
    <XPathsRequest>
</MaskDataConfiguration>
```

If the XML payload contains a namespace and prefix:

```
<myco:employee xmlns:myco="http://example.com">
    <myco:name>xyz</myco:name>
    <myco:age>50</myco:age>
</myco:employee>
```

Then the mask configuration definition should contain the `<Namespace>`
element:

```
<MaskDataConfiguration>
    <Namespaces>
        <Namespace prefix="myco">http://example.com</Namespace>
    </Namespaces>
    <XPathsRequest>
        <XPathRequest>/myco:employee/myco:name</XPathRequest>
    <XPathsRequest>
</MaskDataConfiguration>
```

If the XML Payload has a namespace but no prefix, meaning the default namespace:

```
<employee xmlns="http://example.com">
    <name>xyz</name>
    <age>50</age>
</employee>
```

Then the mask configuration should still contain the `<Namespace>` element:

```
<MaskDataConfiguration>
    <Namespaces>
        <Namespace prefix="myco">http://example.com</Namespace>
    </Namespaces>
    <XPathsRequest>
        <XPathRequest>/myco:employee/myco:name</XPathRequest>
    <XPathsRequest>
</MaskDataConfiguration>
```