Tokenization API

JSON-RPC

The AuricVault® tokenization API uses the JSON-RPC protocol. Client software POSTs a JSON-RPC formatted request object to the service. The AuricVault® service returns a JSON response object that describes the result of the transaction.

Request Notes

  • The params value in the JSON-RPC request is a single-element list containing a dictionary of parameters specific to the method being called.

  • The id parameter is used to track asynchronous transactions. This is typically only used from browser-side connections. The id does not need to be unique.

  • All HTTPS calls to the service must verify the authenticity of the presented HTTPS certificate. Not validating the certificate’s authenticity leaves your system open to a Man in the Middle attack.

  • All HTTPS communications must use TLSv1.2.

Response Notes

  • The id sent in the request is returned in the response.

  • If the returned error value is null, then no failures occurred during the request. (You still need to check lastActionSucceeded to determine if everything is successful, even if the error value is null.)

  • elapsedTime is the time taken for the service to process the request. It does not time the network latency to connect.

  • The version returned is the version of the AuricVault® API. This value will be 2.x where x changes over time. Do not interpret this value.

Note

Always use the object returned by the standard JSON decoding package for your language.

  • Do not try to interpret the returned values.

  • Do not assume that the parameters documented here are the only parameters returned.

  • Do not expect the parameters are always returned in the same order.

Auric reserves the right to return additional parameters or change the order in which parameters are returned at any time.

Character Encoding

The AuricVault® service supports UTF-8 encoded token values and stored data. All maximum data sizes are given in bytes.

Maximum Data Sizes

The maximum data sizes for the AuricVault® tokenization are:

  • token ID: 40 bytes

  • stored data: 2,000 bytes

  • X-VAULT-TRACKING-UID HTTP header: 64 ASCII bytes.

Attempting to store token IDs or data larger than the maximum size causes the operation to fail.

Note

Token IDs generated by the service are 19 printable ASCII characters and can include numbers and upper/lower case letters. Token IDs created by the user can contain UTF-8 characters. Token IDs using UTF-8 characters must be 40 bytes or smaller.

Note

Stored data can contain UTF-8 characters. When using UTF-8 characters, check that your data is less than 2,000 bytes.

Custom HTTP Headers

The AuricVault® service uses two custom HTTP headers:

  • X-VAULT-HMAC (required*)

  • X-VAULT-TRACE-UID (optional, but highly recommended)

Note

The browser side session_encrypt and session_decrypt API calls do not use the X-VAULT-HMAC header.

X-VAULT-HMAC

An HMAC (Hash-based Message Authentication Code) is a calculated value used to establish the authenticity and data integrity of a message. HMAC authentication uses a shared secret between sender and receiver. You receive your shared secret string as part of your credentials.

The HMAC is calculated on the full body of the message being delivered. This ensures that your data was not modified en route.

The service uses SHA-512 hashing to calculate the HMAC. Most languages have a cryptographic library module that contains an HMAC function. In Python, for example, you can use the hmac module as follows:

calculated_hmac = hmac.new(
    secret, message_body,
    hashlib.sha512).hexdigest().lower()

Parameters:

  • secret: the shared secret from your credentials.

  • message_body: serialized (i.e., ‘stringified’) version of the JSON object being posted. Always calculate the HMAC on the full message body.

Note

The resulting HMAC hex string is always lowercased.

See HMAC Examples for sample data and code snippets.

X-VAULT-TRACE-UID

This optional HTTP header value is used for debugging purposes. When available, the AuricVault® service uses this value in all its logs. If sent, this value is also returned in the response.

Note

X-VAULT-TRACE-UID must be printable ASCII characters no longer than 64 characters.

JSON Parameters

Credentials

Programmatic access to the AuricVault® tokenization service API requires the following three credentials:

Code

Meaning

configurationId

The primary identifier for the business.

mtid

The Merchant’s Tokenization Id associated with the account.

secret

A shared secret between you and the service.

Configurations may have more than one mtid. You can think of the mtid value as representing a role – roles define permissions.

The secret is never transmitted. It is used to calculate the HMAC value used for authentication. The HMAC must be submitted with all transactions that originate from your server. Only browser-side tokenization calls do not require HMAC (because that would require the secret to be exposed in the browser).

Timestamp

All the JSON-RPC calls except session_encrypt and session_decrypt require a Unix timestamp parameter. The service requires that time stamps be reasonably close to the time at which the transaction is received. Since the timestamp parameter is included in the HMAC calculation, this reduces the opportunity for a malicious play-back attack on your transactions. If the time stamp is much earlier or later than expected, you receive a response saying the transaction time is not correct. The response shows how the service interpreted the timestamp parameter and what it sees as the current time. This is a helpful debugging device if you are running into problems with time zones.

Note

Please refer to your specific programming language for details on generating a Unix time stamp. The service requires the timestamp parameter be an integer (some libraries return fractions of a second as well). Also be aware of languages such as JavaScript that return the time stamp in milliseconds, not seconds.

The Unix time stamp must be generated for the UTC time zone, not your local time zone.

When working with the AuricVault® service it is important to keep your own server properly synchronized to a network time server. Your call to the service will fail if the time stamp on your message is more than five (5) seconds into the future or 30 seconds into the past.

last4

The following methods have an optional last4 parameter:

  • generate_token

  • encrypt

  • session_encrypt

When storing credit card account numbers, the returned token typically ends with the last four digits of the plaintext card number. This allows you to display the last four digits of a credit card number on a website or data entry screen.

The encrypt and session_encrypt methods automatically extract the last four characters of the plaintext and use that as the last four characters of the token. You can override this default behavior by providing the last four characters to be used.

Since the generate_token method stores already encrypted data, the method cannot automatically extract the last four digits of the plaintext. If you do not include a last4 parameter in the call, the generated token will end with four ‘x’ characters.

Note

That last4 data is four characters, not four digits. You can include any four printable UTF-8 encoded characters.

Note

The last four characters are automatically extracted only when the plaintext data to be encrypted is longer than eight characters. If the plaintext data is less than eight characters, and you do not provide a last4 value, the last four characters of the generated token are set to ‘xxxx’.

Retention and Segment

Every JSON-RPC method that stores tokens has mandatory retention and segment parameters. See the Retention Policies and Information Segmentation sections for usage.

When using the browser-side session_encrypt call, the retention and segment parameters are sent with the get_encrypt_session method. This stores your desired retention period for use by the session_encrypt method and allows you to control the retention period and segmentation in your server-side code vs. the browser-side.

Vault-Managed Encryption Methods

These methods allow the service to handle all the encryption and key management requirements. Support is provided for browser-side tokenization/encryption.

  • encrypt

  • reencrypt

  • decrypt

  • session_encrypt

  • session_decrypt

encrypt

Encrypt a plaintext value and return a generated token. The generated token is stored in the vault. The last4 parameter is optional.

Sample Request
{"params": [{
    "configurationId": "abc",
    "mtid": "123",
    "segment": "543",
    "retention": "big-year",
    "last4": "",
    "plaintextValue": "4111111111111111",
    "utcTimestamp": "1401309530"
    },
    ],
 "id": 1,
 "method": "encrypt"}
Sample Response
{"id":1,
 "result":{
    "version":"2.0",
    "lastActionSucceeded":1,
    "token":"Jyhj3GfKZv0F7Vb1111",
    "elapsedTime":"0.0117"},
"error":null}

encrypt (with existing token)

Encrypt a plaintext value and store it using the passed-in token identifier. This allows you to migrate tokens you already have to the AuricVault® service and maintain the same token identifier in your databases.

Sample Request
{"params": [{
    "configurationId": "abc",
    "mtid": "123",
    "segment": "543",
    "retention": "big-year",
    "plaintextValue": "4111111111111111",
    "token": "SBLIQRPSCBNYQRBFYMH",
    "utcTimestamp": "1401309530"
    }],
 "id": 1,
 "method": "encrypt"}
Sample Response
{"id":1,
 "result":{
    "version":"2.0",
    "lastActionSucceeded":1,
    "token":"SBLIQRPSCBNYQRBFYMH",
    "elapsedTime":"0.0115"},
"error":null}

reencrypt

Submit new plaintext data to be encrypted for an existing token.

Sample Request
{"params": [{
    "configurationId": "abc",
    "mtid": "123",
    "segment": "543",
    "retention": "big-year",
    "plaintextValue": "4111111111111111",
    "token": "JVY1hlZ9qQ0UsJf1111"
    "utcTimestamp": "1401309530"
    }],
 "id": 1,
 "method": "reencrypt"}
Sample Response
{"id":1,
 "result":{
    "version":"2.0",
    "lastActionSucceeded":1,
    "elapsedTime":"0.0117"},
"error":null}

decrypt

Retrieve the decrypted plaintext.

Sample Request
{"params": [{
    "configurationId": "abc",
    "mtid": "123",
    "token": "DAiO2uurxd0GllMrld!",
    "utcTimestamp": "1401310050"
    }],
 "id": 1,
 "method": "decrypt"}
Sample Response
{"id":1,
 "result":{
    "version":"2.0",
    "lastActionSucceeded":1,
    "plaintextValue":"Sample Unicode: Héllø World!",
    "elapsedTime":"0.0106"},
 "error":null}

session_encrypt

The session_encrypt method is similar to the encrypt method. The only difference is the use of a sessionId vs. configurationId, mtid, retention and segment parameters. This method is designed to be called from a browser-based JavaScript AJAX call. Refer to the get_encrypt_session call for details.

As with the standard encrypt call, the last4 parameter is optional.

Sample Request
{"params": [{
    "sessionId": "5Bc4zG5u3ABBTAlr0",
    "last4": "",
    "plaintextValue": "4111111111111111",
    "utcTimestamp": "1401310376"
    }],
 "id": 1,
 "method": "session_encrypt"}
Sample Response
{"id":1,
 "result":{
    "version":"2.0",
    "lastActionSucceeded":1,
    "token":"6Q1LzVTCOk07TA1111",
    "elapsedTime":"0.0125"},
 "error":null}

session_decrypt

This method is the browser-side equivalent of the standard decrypt method. The only difference is the use of a sessionId vs. configurationId, mtid, retention and segment parameters. This method is designed to be called from a browser-based JavaScript AJAX call. Refer to the get_decrypt_session call for details.

Sample Request
{"params": [{
    "sessionId": "SLdqjhGPTc0qvXIms",
    "token": "e2KuSQXMyT0T6Gtrld!",
    "utcTimestamp": "1401310860"
    }],
 "id": 1,
 "method": "session_decrypt"}
Sample Response
{"id":1,
 "result":{
    "version":"2.0",
    "lastActionSucceeded":1,
    "plaintextValue":"4111111111111111",
    "elapsedTime":"0.0075"},
 "error":null}

Token Management Methods

  • delete-token

  • token-info

  • touch-token

delete_token

Delete previously-stored tokens.

Note

Deleting an already-deleted token returns a “Token not found…” error (VLT-176). The reason this is an error is that the token might be there, but you might not have access to the segment within which the token is stored.

The service returns the same message for both a not-found token and a token that exists, but to which you do not have permission. This ensures the existence of the token does not leakto a third party that should not have access to the data.

Sample Request
{"params": [{
    "configurationId": "abc",
    "mtid": "123",
    "token": "e7c469cf-45fa-4d29-9b36-054cabe40e67",
    "utcTimestamp": "1401311686"
    }],
 "id": 1,
 "method": "delete_token"}
Sample Response
{"id":1,
 "result":{
    "version":"2.0",
    "lastActionSucceeded":1,
    "elapsedTime":"0.0125"},
 "error":null}

token_info

Retrieve information about a token. Useful for finding out if a token exists in the system without needing to retrieve the actual data.

An isVaultEncrypted return value of “t” indicates the information associated with this token is encrypted by the AuricVault® service.

Requesting information on a non-existant token returns in an error message and a lastActionSucceeded value of 0 (zero).

Note

token_info does not update the token’s last accessed value.

Sample Request
{"params": [{
    "configurationId": "abc",
    "mtid": "123",
    "token": "Uvsr6MLnPb0G5E7rypt",
    "utcTimestamp": "1401311914"
    }],
 "id": 1,
 "method": "token_info"}
Sample Response
{"id":1,
 "result":{
    "version":"2.0",
    "lastActionSucceeded":1,
    "elapsedTime":"0.0059",
    "tokenExists":"t",
    "tokenCreatedDate":"2014-05-28 11:22:55-0400",
    "lastAccessedDate":"2014-05-29 21:22:55-0400",
    "segment":"543"
    "retention":"big-year",
    "isVaultEncrypted":"t"},
 "error":null}

touch_token

The touch_token method is similar to the token_info method except that it does update the token’s last accessed date time stamp. This method is used to reset the start of the retention period to the current date/time.

Touching a non-existing token returns a lastActionSucceeded of 0 and an error message.

Sample Request
{"params": [{
    "configurationId": "abc",
    "mtid": "123",
    "token": "e5f8ab2a-c8b5-4ab8-acbd-d2501a30b617",
    "utcTimestamp": "1401312848"
    }],
 "id": 1, "method":
 "touch_token"}
Sample Response
{"id":1,
 "result":{
    "version":"2.0",
    "lastActionSucceeded":1,
    "elapsedTime":"0.0045",
    "tokenExists":"t",
    "tokenCreatedDate":"2014-05-28 11:22:55-0400",
    "lastAccessedDate":"2014-05-29 21:32:55-0400",
    "segment":"543"
    "retention":"big-year",
    "isVaultEncrypted":"f"},
 "error":null}

Locally-Managed Encryption Methods

These methods are used to store and retrieve data that is encrypted/decrypted on your local server. All encryption and key management services must be maintained locally to meet your security policy requirements.

Auric has no knowledge of your plaintext and cannot decrypt under any circumstances.

  • store-token

  • generate-token

  • retrieve-token

  • update-token

Note

These methods are provided for integration with some Auric legacy products and services. Auric recommends not using locally-managed encryption unless you are integrating with a legacy system.

store_token

The store_token method allows you to create and store your own tokens. Use when you need to maintain token values in a specific format.

Sample Request
{"params": [{
    "configurationId": "abc",
    "mtid": "123",
    "segment": "543",
    "retention": "big-year",
    "encryptedValue": "38xljsAlkwxo3x==",
    "token": "90809171-7740-4a19-a87f-4b6cb6181871",
    "utcTimestamp": "1401306940"
    }],
 "id": 1,
 "method": "store_token"}
Sample Response
{"id":1,
 "result":{
    "version":"2.0",
    "lastActionSucceeded":1,
    "elapsedTime":"0.0102"},
 "error":null}

generate_token

The generate_token method requires that only the encryptedValue be provided. The response contains the token randomly generated by the service.

Sample Request
{"params": [{
    "configurationId": "abc",
    "mtid": "123",
    "segment": "543",
    "retention": "big-year",
    "last4": "1111",
    "encryptedValue": "38xljsAlkwxo3x==",
    "utcTimestamp": "1401308418"
    }],
 "id": 1,
 "method": "generate_token"}
Sample Response
{"id":1,
 "result":{
    "version":"2.0",
    "lastActionSucceeded":1,
    "token":"UZR15fciED0bPr51111",
    "elapsedTime":"0.0091"},
 "error":null}

retrieve_token

Retrieve the stored encrypted data.

Sample Request
{"params": [{
    "configurationId": "abc",
    "mtid": "123",
    "token": "0a6cede7-c833-4f38-8eea-bf729f13a05d",
    "utcTimestamp": "1401309061"
    }],
 "id": 1,
 "method": "retrieve_token"}

update_token

Update the encrypted data for a previously stored token.

Sample Request
{"params": [{
    "configurationId": "abc",
    "mtid": "123",
    "segment": "543",
    "retention": "big-year",
    "encryptedValue": "xxxENCRYPTEDVALUExxx",
    "token": "JVY1hlZ9qQ0UsJf1111",
    "utcTimestamp": "1401414119"
    }],
 "id": 1,
 "method": "update_token"}
Sample Response
{"id":1,
 "result":{
    "version":"2.0",
    "lastActionSucceeded":1,
    "elapsedTime":"0.0120"},
 "error":null}

Session Management Methods

The browser-side tokenization (session_encrypt) and detokenization (session_decrypt) calls require you to first obtain a sessionID, which you then pass to the browser.

For security, the get_xxx_session calls should never be made from the browser as they expose your credentials.

There are two API calls for obtaining session IDs:

  • get_encrypt_session

  • get_decrypt_session

Note

The sessionId can only be used once and must be used within ten (10) minutes of being created.

get_encrypt_session

The get_encrypt_session call requires you set the retention and segment values for the token you will create from the browser. The sessionId returned by the get_encrypt_session call can only be used with the browser-side session_encrypt API call. An error is returned if you attempt to use it to decrypt (detokenize) a token.

Sample Request
{"params": [{
    "configurationId": "abc",
    "mtid": "123",
    "segment": "543",
    "retention": "big-year",
    "utcTimestamp": "1401313120"
    }],
 "id": 1,
 "method": "get_encrypt_session"}
Sample Response
{"id":1,
 "result":{
    "version":"2.0",
    "lastActionSucceeded":1,
    "sessionId":"TsclZ0cU27g2poWLr",
    "elapsedTime":"0.0078"},
 "error":null}

get_decrypt_session

The get_decrypt_session requires you to provide a tokenList parameter with one or more tokens. The session_decrypt call is limited to decrypting tokens from this list. Any attempt to session_decrypt a token not on this list returns an error.

The sessionId returned by the get_decrypt_session call can only be used with the browser-side session_decrypt API call. An error is returned if you attempt to use it to encrypt (tokenize) data.

This call supports a list of tokens in preparation for future functionality allowing you to detokenize multiple tokens with one API call.

Note

The tokenList parameter is limited to a maximum of five (5) tokens.

Sample Request
{
 "params": [{
    "configurationId": "abc",
    "mtid": "123",
    "tokenList": ["WThTuTms5b0VGxr1111"],
    "utcTimestamp": "1572013476"
    }],
 "id": 1,
 "method": "get_decrypt_session"
 }
Sample Response
{"id":1,
 "result":{
    "version":"2.0",
    "lastActionSucceeded":1,
    "sessionId":"TsclZ0cU27g2poWLr",
    "elapsedTime":"0.0078"},
 "error":null}