Skip to main content
This page shows how to enable and authenticate with the CryptoHub APIs so that applications can submit data for tokenization and detokenization. For background on the tokenization model, see Understanding tokenization. To create the profiles that the API operates on, see Tokenization requirements and access. You manage token profiles in the CryptoHub client, but you cannot tokenize or detokenize data there. Data is always submitted through one of two distinct interfaces:
  • The v2 REST API, under the base path /api/v2/token-profiles, called from software such as Postman or your own application.
  • The Host API, a set of command codes sent over the host command channel.
The two interfaces are independent. Choose one based on how your application already integrates with the CryptoHub, and authenticate to it as described below.

​
Use the v2 REST API

The v2 REST API exposes the full token-profile lifecycle plus tokenize, detokenize, batch, and tracking operations under the base path /api/v2/token-profiles. Each operation targets a profile by its UUID.
Earlier documentation referenced a /kmes/v7/token-profiles base path. CryptoHub 7.3.0.x uses /api/v2/token-profiles. Update any client that still calls the older path.
The base path supports the following endpoints:
Method and pathPurpose
POST /api/v2/token-profilesCreate a token profile.
GET /api/v2/token-profiles/stubsList token profiles.
GET /api/v2/token-profiles/{uuid}Retrieve a token profile.
PATCH /api/v2/token-profiles/{uuid}Modify a token profile.
DELETE /api/v2/token-profiles/{uuid}Delete a token profile.
POST /api/v2/token-profiles/{uuid}/tokenizeTokenize a single value.
POST /api/v2/token-profiles/{uuid}/detokenizeDetokenize a single token.
POST /api/v2/token-profiles/{uuid}/batch-tokenizeTokenize multiple values in one request.
POST /api/v2/token-profiles/{uuid}/batch-detokenizeDetokenize multiple tokens in one request.
POST /api/v2/token-profiles/{uuid}/track-tokenizeTokenize with tracking.
POST /api/v2/token-profiles/{uuid}/track-detokenizeDetokenize with tracking.
GET /api/v2/token-profiles/template/namesList the available profile templates.
GET /api/v2/token-profiles/template/{name}Retrieve a profile template.
PATCH /api/v2/token-profiles/{uuid}/permissionsSet the Control Rules that govern access to the profile.
Batch and Partial detokenization behavior is governed by the profile’s Control Rules, not by the request. A caller can use batch-detokenize only when the matching Control Rule has Allow Batch enabled, and a Partial Control Rule returns only the configured number of revealed characters. See Tokenization requirements and access.
REST API detokenization appears in the clear.Host API detokenization is in the hexadecimal format.

​
Authenticate with the v2 REST API

The v2 REST API uses bearer-token authentication. You log in to obtain a bearer token, then send that token with each request.
1
Authenticate as an identity that has permission to call the endpoints you need. The Control Rules on each profile decide which roles may tokenize, detokenize, or detokenize partially.
2
Obtain a bearer token for the session. See Using bearer tokens and Bearer token session.
3
Send the bearer token in the Authorization header on each call to an /api/v2/token-profiles endpoint.
A tokenize request to a profile you are authorized for returns the tokenized value rather than an authorization error.
For the request and response schema of every endpoint, see the token-profiles API reference.

​
Use the Host API

The Host API is a separate interface that sends command codes over the host command channel. Before an application can tokenize through the Host API, an administrator must enable the relevant commands on the unit.

​
Enable host API commands

1
On the left-side menu, go to the Classic Tools tab.
2
Under the Administration heading, select [ GO TO CONFIGURATION TASKS ].
3
Find Host API Options by scrolling or using the search bar. To open it, select it and select [ Edit ], or double-click it.
4
Enable the commands your application uses for tokenization and profile management:
  • CLGR: Manage cloud key group (get, delete, add, retrieve).
  • RKLN: Lookup name.
  • TOKA: Tokenize data.
  • TOKG: Detokenize data.
  • TKGA: Add tokenization profile.
  • TKGD: Delete tokenization profile.
Following the principle of least privilege, leave every command not required by your integration disabled.
The selected commands show as enabled in Host API Options after you save.

​
Authenticate with the Host API

To authenticate with the Host API, use the RKLO host command and validate with one of the following methods:
  • User password
  • API token
  • PKI challenge and response signature
REST API detokenization appears in the clear.Host API detokenization is in the hexadecimal format.
For help accessing the Host API, contact support@futurex.com.