> ## Documentation Index
> Fetch the complete documentation index at: https://docs.futurex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Step 2: Tokenize and detokenize data

> How to tokenize and detokenize data with a CryptoHub token profile using the v2 REST API, including single, batch, and track operations.

For background on what tokenization does and when to use it, see [Understanding tokenization](/CryptoHub/7.3.0.x/Administrator_guide/Data_protection/Tokenization/Tokenization_on_CryptoHub/Understanding_tokenization). To build the profile that these requests run against, see [Create tokenization profiles](/CryptoHub/7.3.0.x/Administrator_guide/Data_protection/Tokenization/Managing_tokenization/Create_a_tokenization_profile).

In CryptoHub 7.3.0.x, tokenization runs against a token profile, which binds an algorithm, a key, and format rules together. You do not build the transformation per request. You select the profile by its UUID and send it data. Before you tokenize, make sure you have:

* A token profile created on the **Tokenization** page, with a backing key. See [Create tokenization profiles](/CryptoHub/7.3.0.x/Administrator_guide/Data_protection/Tokenization/Managing_tokenization/Create_a_tokenization_profile).
* At least one Control Rule on the profile's **Access** tab that grants your role the operation you intend to run (tokenize, detokenize, partial detokenize, or batch). See [Tokenization requirements and access](/CryptoHub/7.3.0.x/Administrator_guide/Data_protection/Tokenization/Tokenization_profiles/Control_rules_and_access).
* API access enabled and a way to authenticate. See [Enable API access](/REST_API/Docs/Use_cases/Tokenization/Enable_API_access).

## Choose an interface

You can run tokenization through either of two interfaces.

* **REST API**: the v2 endpoints under `/api/v2/token-profiles/{uuid}`. This is the recommended interface and the one documented here.
* **Host API**: the binary command set (`TOKA` to tokenize, `TOKG` to detokenize) for host-to-HSM integrations. The Host API is distinct from the REST API and returns detokenized data in a different format. For help with the Host API, contact [support@futurex.com](mailto:support@futurex.com).

<Note>
  REST API detokenization appears in the clear.

  Host API detokenization is in the hexadecimal format.
</Note>

## Tokenize a single value

Tokenize one message by posting it to the profile's `tokenize` endpoint. The request body uses `message`. A successful response returns a `token` string.

<Steps>
  <Step>
    Authenticate to the CryptoHub REST API and note the UUID of the token profile you want to use. The UUID appears on the profile in the **Tokenization** page and is returned by `GET /api/v2/token-profiles/stubs`.
  </Step>

  <Step>
    Send the value to the profile's `tokenize` endpoint.

    ```http Tokenize request theme={null}
    POST /api/v2/token-profiles/{uuid}/tokenize
    Content-Type: application/json

    {
      "message": "123456"
    }
    ```
  </Step>

  <Step>
    Read the token from the `response.token` field of the reply.

    ```json Tokenize response theme={null}
    {
      "success": true,
      "errorCode": "Success",
      "response": {
        "@type": "api.v2.dp.TokenizationResponse",
        "token": "0274266941673144"
      }
    }
    ```

    <Check>
      `success` is `true` and `errorCode` is `Success`. Store the returned `token` in place of the original value.
    </Check>
  </Step>
</Steps>

<Note>
  If the request fails, `success` is `false` and `errorCode` carries a machine-readable reason such as `ArgumentParseError`, `InvalidSelection`, or `NotAuthorized`. A `403` indicates the caller's role is not granted the operation by a Control Rule on the profile's **Access** tab.
</Note>

## Detokenize a single value

Reverse a token by posting it to the profile's `detokenize` endpoint. The request body uses `token`, not `message`. Include `iv` only when the profile uses an initialization vector that was returned at tokenization time.

<Steps>
  <Step>
    Confirm that your role is granted detokenization on the profile, either as a full or a partial Control Rule. The backing key must also allow the required reverse operation.
  </Step>

  <Step>
    Send the token to the profile's `detokenize` endpoint.

    ```http Detokenize request theme={null}
    POST /api/v2/token-profiles/{uuid}/detokenize
    Content-Type: application/json

    {
      "token": "0274266941673144"
    }
    ```
  </Step>

  <Step>
    Read the recovered value from the `response.message` field of the reply.

    ```json Detokenize response theme={null}
    {
      "success": true,
      "errorCode": "Success",
      "response": {
        "@type": "api.v2.dp.DetokenizationResponse",
        "message": "123456"
      }
    }
    ```

    <Check>
      `success` is `true` and `response.message` holds the original cleartext value.
    </Check>
  </Step>
</Steps>

<Note>
  A partial Control Rule returns the value with only a configured number of characters revealed and the rest replaced by the rule's mask character. See [Tokenization requirements and access](/CryptoHub/7.3.0.x/Administrator_guide/Data_protection/Tokenization/Tokenization_profiles/Control_rules_and_access).
</Note>

## Tokenize or detokenize in batches

When you have several values, use the batch endpoints to process them in one request. Batch operations require a Control Rule that allows batch on the profile. The response returns results in the same order as the request.

* Batch tokenize takes `messages` and returns `tokens`.
* Batch detokenize takes `tokens` and returns `messages`.

```http Batch tokenize request theme={null}
POST /api/v2/token-profiles/{uuid}/batch-tokenize
Content-Type: application/json

{
  "messages": ["123456", "654321"]
}
```

```json Batch tokenize response theme={null}
{
  "success": true,
  "errorCode": "Success",
  "response": {
    "@type": "api.v2.dp.BatchTokenizationResponse",
    "tokens": ["0274266941673144", "0279785857534399"]
  }
}
```

```http Batch detokenize request theme={null}
POST /api/v2/token-profiles/{uuid}/batch-detokenize
Content-Type: application/json

{
  "tokens": ["0274266941673144"]
}
```

## Tokenize or detokenize track data

For payment card track data, use the track endpoints. These take and return a `track` string rather than a `message`.

* Track tokenize takes `track` and returns the tokenized `track`.
* Track detokenize takes the tokenized `track` and returns the original `track`.

```http Track tokenize request theme={null}
POST /api/v2/token-profiles/{uuid}/track-tokenize
Content-Type: application/json

{
  "track": "4111111111111111=25121010000000000000"
}
```

```json Track tokenize response theme={null}
{
  "success": true,
  "errorCode": "Success",
  "response": {
    "@type": "api.v2.dp.TrackTokenizationResponse",
    "track": "tokenized-track-data"
  }
}
```

## Reference

For the full request and response schema of every endpoint, see the [token-profiles endpoints](/REST_API/Docs/Key_management/Token_profiles) and the generated reference for the endpoints under `/api/v2/token-profiles/` (including `tokenize`, `detokenize`, `batch-tokenize`, `batch-detokenize`, `track-tokenize`, and `track-detokenize`).