Critical Tokenization API
ALTR's Critical Tokenization API enables you to tokenize and scatter data, to retrieve the data from a token, and to dereference data in ALTR's critical tokenization platform. Critical Tokenization is only available for advanced financial data protection use cases; ALTR recommends using the PCI-certified Vaulted Tokenization solution for general PCI, PHI, PII, and sensitive data protection.
Authentication of ALTR's Critical Tokenization requires an API key and secret separate from other ALTR APIs. Creating an API key generates a key secret that can be utilized for the API. Be sure to record the API secret when it is created as it is only available once.
To create a critical tokenization API key:
Select → in the Navigation menu.
Click the API tab.
Click Add New.
Enter an API Key Name.
(Optional) Enter a Description.
Select the Permissions. Options are:
Read—Allows the key holder to retrieve data from the API
Write—Allows the key holder to modify data in ALTR through the API
Dereference Tokens—Invalidates the reference token and prevents data from being accessed.
Token Determinism Option—Gives the API key the ability to set a token determinism for each batched write transaction.
Add IP Addresses that are specific public IPs to whitelist. Supported options are:
CIDR notion
IPv4
IPv6
Click Add Application; the New API Key Secret dialog displays.
Click Copy to copy the API key secret.
Important
Be sure to save the API key secret; this is the only time you are able to copy the secret.
Disable Critical Tokenization API Key
When the API key is created, it is enabled by default. Disable a key to prevent users from using it to authenticate API requests. If you disable a key that is in use, the API request will fail. Disabling an API key does not delete it from ALTR.
To disable a critical tokenization API key:
Select → in the Navigation menu.
Click the API tab.
Select the API key you wish to disable.
Click DISABLE APPLICATION link.
The Critical Tokenization API requires the following headers for all requests:
Field | Type | Description |
|---|---|---|
Content-Type | String | Must be |
Authorization | String | The accepted format is |
X-ALTR-DATE | Date | The datetime used in the authorization signature. If this is more than 15 minutes past the server's internal clock, the request will be rejected. |
Content-Length | Number | Required only for PUT calls. This field indicates the size of the request. Depending on application, the request will be rejected with a 403 if the request is over 8KB or a 509 status code if the request if over 500kb. |
Javascript function to generate a valid authorization header:
//prepare a HTTP Post to be made
var curDate = new Date();
var date = curDate.toString();
var payload = 'POST\n\n' + date + '\n';
let base64 = crypto.createHmac('sha256', SECRET).update(payload).digest("base64");
var auth = 'ALTR '+ API_KEY + ':' + base64;Example Request Headers:
date = new Date();
payload = 'POST\n\n' + date + '\n';
API_KEY = <your API key>;
SECRET = <your API secret>;
{
"X-ALTR-DATE": date,
"Authorization": "ALTR " + API_KEY + ":" + base64(hmac-sha256(payload, SECRET)),
"Content-Type": "application/json",
"Content-Length": 12345
}The Critical Tokenization API may include the following headers in responses:
Field | Type | Description |
|---|---|---|
X-Bytes-Consumed | Number | The number of bytes written to the distributed ledger and counted against the key's organization. The number may differ from the Content-Length header because the string representation of the data is written to the distributed ledger. |
X-Overflow-Data | Boolean | This flag is set if any single value is greater than 3kb or if the entire batch is greater than 500kb. |
Example Response Headers
{
"X-BYTES-CONSUMED": 12345,
"X-OVERFLOW-DATA": true
}This endpoint takes in a batch of up to 1024 key:value pairs. The values are scattered and tokenized, with the resulting tokens being returned as key:value pairs. The keys can be any identifier and are used to identify elements within the batch. Values must be no larger than 3kb in size. Requests above 500kb in size will be rejected. The PostBatch operation offers read-after-write consistency and each token is available when the response is sent.
Example Request:
{
"key1": "value1",
"key2": "value2"
}Example 200 Response:
HTTP/1.1 200 OK
{
"key-1": "token1",
"key-2": "token2",
"overflow-key": null
}Example 400 Response:
HTTP/1.1 400 Bad Request
{
"success": false,
"response": {
"error_type": "bad_request",
"error_message": "Invalid JSON detected. Failed unique key check"
}
}Example 400 Response:
HTTP/1.1 400 Bad Request
{
"success": false,
"response": {
"error_type": "bad_request",
"error_message": "Organization data cap exceeded"
}
}Example 401 Response:
HTTP/1.1 401 Authentication Required
{
"success": false,
"response": {
"error_type": "unauthorized",
"error_message": "API key must be included in header."
}
}Example 403 Response:
HTTP/1.1 403 Forbidden
{
"success": false,
"response": {
"error_type": "forbidden",
"error_message": "API key does not have write permission."
}
}Example 503 Response:
HTTP/1.1 503 Internal Server Error
{
"success": false,
"response": {
"error_type": "internal_error",
"error_message": "Unable to process request at this time."
}
}This endpoint takes in a batch of up to 1024 key:value pairs where the values are existing tokens. The results are unscattered and returned as key:value pairs, with the values being the original detokenized data. Any key:value pairs that are not valid tokens are returned as-is. If any token is associated with data >3kb, the returned value is NULL. If the total size of the request exceeds 500kb, the request is rejected with a 509 status code.
Example Request:
{
"key1": "token1",
"key2": "token2"
}Example 200 Response
HTTP/1.1 200 OK
{
"key1": <data for token1>,
"key2": <data for token2>
}Example 400 Response:
HTTP/1.1 400 Bad Request
{
"success": false,
"response": {
"error_type": "bad_request",
"error_message": "Invalid JSON detected. Failed unique key check"
}
}Example 401 Response:
HTTP/1.1 401 Authentication Required
{
"success": false,
"response": {
"error_type": "unauthorized",
"error_message": "API key must be included in header."
}
}Example 403 Response:
HTTP/1.1 403 Forbidden
{
"success": false,
"response": {
"error_type": "forbidden",
"error_message": "API key does not have read permissions."
}
}Example 404 Response:
HTTP/1.1 404 Not Found
{
"success": false,
"response": {
"error_type": "resource_not_found",
"error_message": "The following tokens could not be found: "
}
}Example 503 Response:
HTTP/1.1 503 Internal Server Error
{
"success": false,
"response": {
"error_type": "internal_error",
"error_message": "Unable to process request at this time."
}
}This endpoint invalidates a referenceToken, preventing the corresponding data from being accessed.
Example Request Headers:
date = new Date();
payload = 'DELETE\n' + referenceToken + '\n' + date + '\n';
API_KEY = <your API key>;
SECRET = <your API secret>;
{
"X-ALTR-DATE": date,
"Authorization": "ALTR " + API_KEY + ":" + base64(hmac-sha256(payload, SECRET))
}Example 204 Response:
HTTP/1.1 204 No Content
Example 401 Response
HTTP/1.1 401 Authentication Required
{
"success": false,
"response": {
"error_type": "unauthorized",
"error_message": "API key must be included in header."
}
}Example 403 Response
HTTP/1.1 403 Forbidden
{
"success": false,
"response": {
"error_type": "forbidden",
"error_message": "API key does not have write permission."
}
}Example 404 Response
HTTP/1.1 404 Not Found
{
"success": false,
"response": {
"error_type": "resource_not_found",
"error_message": "Token could not be found"
}
}Example 503 Response
HTTP/1.1 503 Internal Server Error
{
"success": false,
"response": {
"error_type": "internal_error",
"error_message": "Unable to process request at this time."
}
}PUT /api/v1/single/
Example Request Headers:
date = new Date();
payload = 'POST\n\n' + date + '\n';
API_KEY = <your API key>;
SECRET = <your API secret>;
{
"X-ALTR-DATE": date,
"Authorization": "ALTR " + API_KEY + ":" + base64(hmac-sha256(payload, SECRET)),
"X-ALTR-METADATA": "<metadata>",
"X-Content-Length-Hint": 500
}Example 200 Response:
HTTP/1.1 200 OK
{
"success": true
"response": {
"data": {
"referenceToken": <token>
}
}
}GET /api/v1/single/:referenceToken
Example Request Headers
date = new Date();
payload = 'GET\n' + referenceToken + '\n' + date + '\n';
API_KEY = <your API key>;
SECRET = <your API secret>;
{
"X-ALTR-DATE": date,
"Authorization": "ALTR " + API_KEY + ":" + base64(hmac-sha256(payload, SECRET))
}Example Response: On success, the associated data is returned as an octet-stream in the response's body.
GET /api/v1/single/:referenceToken/metadata
Example Request Headers:
date = new Date();
payload = 'GET\n' + referenceToken + '\n' + date + '\n';
API_KEY = <your API key>;
SECRET = <your API secret>;
{
"X-ALTR-DATE": date,
"Authorization": "ALTR " + API_KEY + ":" + base64(hmac-sha256(payload, SECRET))
}Example 200 Response:
{
"success": true,
"metadata": "filename.txt"
}GET /api/v1/single/:referenceToken/status
Example Request Headers
date = new Date();
payload = 'GET\n' + referenceToken + '\n' + date + '\n';
API_KEY = <your API key>;
SECRET = <your API secret>;
{
"X-ALTR-DATE": date,
"Authorization": "ALTR " + API_KEY + ":" + base64(hmac-sha256(payload, SECRET))
}Example 200 Response
HTTP/1.1 200 OK
{
"success": true,
"response": {
"data": {
"token_active": true,
"data_protected": false,
"data_available": true
}
}
}