The ShieldConex API

There are 4 types of operation you can perform with the API. The most essential calls will revolve around Tokenization and Detokenization, however we also provide you with tools to create a more intelligent or easy to monitor solution. These come in the form of our Validate and Healthcheck calls, which allow you to check the status of data and operations. See the sections below for more details on each.

Before you can make any of these calls, you'll need to implement API Authentication

📘

Note

If you're planning to tokenize via iFrame, you should know about the Query Tokenized Data API call in our Tokenization docs. You can use it to read data that was entered into a ShieldConex iFrame element. This is strictly intended for use with the iFrame implementation.

Tokenization

When using the API directly for data tokenization, it is your responsibility to handle any validation and gathering of data. This is only a single step to tokenize data; it will not be held anywhere temporarily for retrieval as is the case with the iFrame solution. Once you send the data, you will receive tokenized values for the same data and a BFID. The BFID and tokenized values are necessary to detokenize the data.

Here are some important items to note for Data Tokenization using the API:

• The authentication is sent in the header with each API call.
• You must enter all required values that exist within a template. If any values are missing, you will receive an error response.
• 'Reference' is simply a reference value that you can use to track API requests and responses. Reference is not a mandatory entry, it is solely for tracking purposes.
• Order of values in the "values" array is not guaranteed; use the "name" property to match them, never by index.

You can find our full tokenization guide here

Detokenization

Data retrieval is the same for both implementations. You take the ID given and the tokenized values to get the plain values. You can call this whenever needed, no need to resubmit for new tokens. When you are done with the sensitive data, remove them from memory until needed again.

See our detokenization guide here.

Example

This example is in Node.js, but any server side language that can call an API will work. Axios is a convenient library for making API calls.

var fnGetValues=function(strBfid,arrValues){
	axios({
	    "method": 'post',
	    "headers": {"Authorization": strAuthYourVariable,"Accept": 'application/json',"Content-Type": 'application/json'},
	    "url": 'https://secure-cert.shieldconex.com/api/tokenization/detokenize',
	    "data": JSON.stringify({"bfid":strBfid,"values":arrValues})
	  }).then(function (objResponse) {
	  	//this is where you get the real data values to use and wipe from memory ASAP
	  	console.log('got the values',objResponse.data.values);
	  });
}

Validation

We provide validation endpoints so that you can automatically test connectivity to the ShieldConex platform or ensure that a template is correctly provisioned and continuing to work as expected. See the full guide on validation here.

Healthchecks

We also offer additional endpoints to perform health-checks on the tokenization engine to ensure that tokenization and detokenization are occurring properly for a given template. This is typically used for monitoring and alert systems or more robust error handling. You can find the healthcheck guide here.