---
schema_version: "1"
id: 15adf1e2c3863a23cdeca09b2748d8945afe865d97f391222a2a0d0c1c41b5dc
title: Tokenization Policy
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/mule-gateway/policies-included-tokenization.md
canonical_url: https://docs.mulesoft.com/mule-gateway/policies-included-tokenization
source_site: docs.mulesoft.com
content_type: documentation
content_hash: afbbf6eab52d93f4bce441f152f09d3739926f69f1dccd033153e2b77fb77bc6
description: MuleSoft Documentation Site
latest: true
---
---
product: Mule Gateway
keywords: tokenization, api gateway, mule gateway, gateway, policy
---

# Tokenization Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><div><div><p>Tokenization</p></div></div></td></tr><tr><td><p><strong>Summary</strong></p></td><td><div><div><p>Transforms sensitive data into a nonsensitive equivalent, named token</p></div></div></td></tr><tr><td><p><strong>Category</strong></p></td><td><div><div><p>Security</p></div></div></td></tr><tr><td><p><strong>First Mule version available</strong></p></td><td><div><div><p>v4.1.1</p></div></div></td></tr><tr><td rowspan="3"><p><strong>Returned Status Codes</strong></p></td><td><div><table><colgroup><col> <col></colgroup><tbody><tr><td rowspan="3"><div><div><p>400</p></div></div></td><td><div><div><p>A token is invalid, or the tokenization failed.</p></div></div></td></tr><tr><td><div><div><p>The provided expression is invalid or returns no result to tokenize.</p></div></div></td></tr><tr><td><div><div><p>The status code to be returned can be configured.</p></div></div></td></tr></tbody></table></div></td></tr><tr><td><div><div><p>502 - Connection to the tokenization service is unavailable or not configured.</p></div></div></td></tr></tbody></table>

## Summary

Tokenization is the process of masking a value or piece of information that can be considered
sensitive data into a token that can be mapped back to its original value using detokenization
concepts. If your API contains sensitive data, the tokenization policy is a highly effective way to
protect it.

The data is displayed in the same format as the original value, but its actual value is not revealed
initially.

> [!NOTE] This policy is designed to work only for Anypoint Runtime Fabric deployments.

Tokenization minimizes the risk of matching the sensitive data to the original value, in case a
third party accesses the data. For example, you can use this policy to hide credit card numbers,
personally identifiable information (PII), protected health information (PHI), and similar sensitive
data.

## Prerequisites

To apply and manage the Tokenization policy, you must have:

- Obtained the **Manage Policies** permission.

- To configure and run the tokenization service, you must have:

  - Installed Runtime Fabric

  - Obtained the **Manage Tokenization Services** permission

- An operating tokenization service

## Scope and Considerations

Before you apply this policy, review the following considerations:

- One instance of the policy supports only one tokenization service.

  All the formats that you configured need to be contained in the same tokenization service.

- You can use one instance of the policy to tokenize a value either in the request or in the
  response, but not in both.

- The policy is not aware of the state of the tokenization service until runtime. If you deleted
  your tokenization service or if it is not operational, the policy cannot establish communication
  with it. This causes all the requests to fail until the service is available again. During policy
  configuration, the services menu displays only the tokenization services that are ready to use.

  If you do not see the service you want, verify if it is already deployed.

## Configuring Policy Parameters

### Mule Gateway

When you apply the policy to your API from the UI, the following parameters are displayed:

<table><colgroup><col> <col> <col></colgroup><thead><tr><th>Element</th><th>Description</th><th>Required</th></tr></thead><tbody><tr><td><div><div><p>Direction</p></div></div></td><td><div><div><p>Whether the values to tokenize are extracted from the request or the response (default).</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Fail on unmatched expressions</p></div></div></td><td><div><div><p>If selected, requests fail when the expression and tokens do not match.</p></div></div></td><td><div><div><p>No</p></div></div></td></tr><tr><td><div><div><p>Services</p></div></div></td><td><div><div><p>The tokenization services available for the current organization and environment. Select the service that you need from the list. Note that the formats available depend on the service that you choose.</p></div></div></td><td><div><div><p>Yes</p></div></div></td></tr><tr><td><div><div><p>Expression</p></div></div></td><td><div><div><p>A selector expression that extracts the information to be tokenized.</p></div><div><p>For example:</p></div><div><div><pre><code data-lang="expression">#[payload.people.creditCardNumber]</code></pre></div></div><div><p>Only expressions using dots as field separators are allowed. While <code>#[payload.people.creditCardNumber]</code> is valid, <code>#[payload[‘people’]]</code> is not.</p></div></div></td><td><div><div><p>No.<br>If you do not specify a selector expression, the policy is applied, but does not tokenize anything from the payload.</p></div></div></td></tr><tr><td><div><div><p>Format</p></div></div></td><td><div><div><p>Type of information to be tokenized. Formats vary depending on the selected service.</p></div><div><p>If you do not see any formats in the list, verify that the tokenization service that you selected contains at least one.</p></div></div></td><td><div><div><p>No<br>If you do not specify a format, the policy is applied but does not tokenize anything from the payload.</p></div></div></td></tr></tbody></table>

## How This Policy Works

The Tokenization policy replaces sensitive parts of a message payload with tokenized values. To
define which information is tokenized, you must provide a selector expression.

### Examples

Suppose that the payload that receives the policy contains the following structure:

```JSON
{
  "name":"Amun Ra",
  "socialSecurityNumber":"365-93-2738"
}
```

If you want to tokenize the social security number, you can use the following selector expression:

```expression
#[payload.socialSecurityNumber]
```

Now, every time the policy receives a request containing a `socialSecurityNumber` key in its top
level, it will extract all the tokens that match the expression you indicated, it will establish a
connection with the tokenization service, and finally it will replace the tokenized values in your
payload with the ones provided by the service.  
If the tokenized value for the Social Security Number in the example were 167-47-9268, your
application will receive the following payload:

```json
{
  "name": "Amun Ra",
  "socialSecurityNumber": "167-47-9268"
}
```

You can configure the Tokenization policy to tokenize values in your payload request or response.

### Tokenize Requests

The following events occur when you tokenize requests:

![A diagram shows a data flow between security, tokenization, and a Mule application](/mulesoft/current/en-us/mule-gateway/_images/policy-mule4-tokenization-67b25.png)

1.  A user performs a request to the application protected by the policy.

2.  The request goes first to Anypoint Security and then to the application Tokenization policy.

3.  The Tokenization policy extracts all tokens that match the selector expression.

4.  The tokenization service receives the tokens, transforms them, and returns the result to the
    policy.

5.  The policy replaces the payload with the tokenized values and forwards it to the Mule
    application.

6.  The Mule application processes the request and returns the result.

### Tokenize Responses

The following events occur when you tokenize responses:

![A diagram shows a data flow of a tokenization service](/mulesoft/current/en-us/mule-gateway/_images/policy-mule4-tokenization-9347d.png)

1.  A user performs a request to the application protected by the policy.

2.  The request goes first to Anypoint Security and then to the application Tokenization policy.

3.  The tokenization policy tokenizes the Mule response and redirects the request without extracting
    anything from the payload.

4.  The Mule application processes the request and returns the result.

5.  The Tokenization policy extracts the tokens from the payload using the selector expression.

6.  The tokenization service receives the tokens, transforms them, and returns the result to the
    policy.

7.  The Tokenization policy sends the response back to the user with the tokenized values in the
    payload.