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

# Detokenization 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>Detokenization</p></div></div></td></tr><tr><td><p><strong>Summary</strong></p></td><td><div><div><p>Returns a tokenized value to its original value. This policy is designed to work only for Anypoint Runtime Fabric deployments.</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>The provided expression is invalid or returns no result to detokenize.</p></div><div><p><strong>NOTE</strong>: You can configure the status code to be returned.</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

Detokenization is the process of returning the previously masked sensitive data back into its
original value to reduce the risk of compromising sensitive information. You can tokenize your data
to replace sensitive information with tokens to reduce the risk of compromising sensitive
information.

For example, an application can require the bank account number or the credit card number for
generating monthly credit card statements. Detokenized sensitive data must always be read under
strict security controls.

## Prerequisites

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

- Obtained the **Manage Policies** permission

- To configure and use 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 must be contained in the same tokenization service.

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

- 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, check to see if it is already deployed.

## Configuring Policy Parameters

### Mule Gateway

When you apply this policy to your API, the following fields are displayed in the UI:

<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 detokenize 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 to be used to extract the information that will be detokenized.</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 detokenize 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 that will be detokenized. Formats may vary depending on the selected service. Choose one format from the list.</p></div><div><p>If you don’t see any formats in the list, verify that the tokenization service selected contains at least one format.</p></div></div></td><td><div><div><p>No<br>If you do not specify a format, the policy is applied but nothing is detokenized from the payload.</p></div></div></td></tr></tbody></table>

## How This Policy Works

The Detokenization policy returns tokenized information within the payload to its original values.
To define which data in the payload is detokenized, you must provide a selector expression.

**Examples**

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

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

If you want to detokenize the social security number, you can use the following selector expression
to specify which piece of information the policy should tokenize:

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

Using this selector, every time the policy receives a request containing a `socialSecurityNumber`
key in its top level, it extracts all the tokens that match the expression you indicated,
establishes a connection with the tokenization service, and replaces the tokenized values in your
payload with the original values.

If the detokenized value for the Social Security Number in the example were _365-93-2738_, your
application would receive the following payload:

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

You can configure the detokenization policy to detokenize values in the request or response of your
payload.

### Detokenizing Requests

The following events occur when detokenizing 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 Detokenization policy.

3.  The Detokenization policy extracts the tokens from the payload using the selector expression.

4.  The detokenization service receives the tokens, returns them to their original sensitive values,
    and sends the result to the policy.

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

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

### Detokenizing Responses

The following events occur when detokenizing 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 Detokenization policy.

3.  The Detokenization policy redirects the request without extracting anything from the payload.

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

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

6.  The detokenization service receives the tokens, returns them to their original sensitive values,
    and sends the result to the policy.

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