Skip to main content
This page shows how to send data to a token profile to be tokenized and how to reverse a token back to its original value in CryptoHub 7.3. For background on what tokenization does and when to use it, see Understanding tokenization. To build the profile that these requests run against, see Create tokenization profiles. 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:

​
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.
REST API detokenization appears in the clear.Host API detokenization is in the hexadecimal format.

​
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.
1
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.
2
Send the value to the profile’s tokenize endpoint.
Tokenize request
POST /api/v2/token-profiles/{uuid}/tokenize
Content-Type: application/json

{
  "message": "123456"
}
3
Read the token from the response.token field of the reply.
Tokenize response
{
  "success": true,
  "errorCode": "Success",
  "response": {
    "@type": "api.v2.dp.TokenizationResponse",
    "token": "0274266941673144"
  }
}
success is true and errorCode is Success. Store the returned token in place of the original value.
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.

​
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.
1
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.
2
Send the token to the profile’s detokenize endpoint.
Detokenize request
POST /api/v2/token-profiles/{uuid}/detokenize
Content-Type: application/json

{
  "token": "0274266941673144"
}
3
Read the recovered value from the response.message field of the reply.
Detokenize response
{
  "success": true,
  "errorCode": "Success",
  "response": {
    "@type": "api.v2.dp.DetokenizationResponse",
    "message": "123456"
  }
}
success is true and response.message holds the original cleartext value.
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.

​
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.
Batch tokenize request
POST /api/v2/token-profiles/{uuid}/batch-tokenize
Content-Type: application/json

{
  "messages": ["123456", "654321"]
}
Batch tokenize response
{
  "success": true,
  "errorCode": "Success",
  "response": {
    "@type": "api.v2.dp.BatchTokenizationResponse",
    "tokens": ["0274266941673144", "0279785857534399"]
  }
}
Batch detokenize request
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.
Track tokenize request
POST /api/v2/token-profiles/{uuid}/track-tokenize
Content-Type: application/json

{
  "track": "4111111111111111=25121010000000000000"
}
Track tokenize response
{
  "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 and the generated reference for the endpoints under /api/v2/token-profiles/ (including tokenize, detokenize, batch-tokenize, batch-detokenize, track-tokenize, and track-detokenize).