Getting Started

• 1: Initial Setup
• 2: Postman Guide
• 3: VS Code Guide

1 - Initial Setup

You can sign-up to Protegrity API Playground using the form on the official API Playground webpage. Within a few minutes you will receive an email from us with your unique API Key and a password. You will use your email and password to login to the Playground via the Login endpoint. On a successuful login you will receive a JWT token. The JWT token, together with your API key, will authenticate your requests to the Playground going forward.

2 - Postman Guide

For organizations handling sensitive data, finding a secure and efficient way to test data protection solutions is crucial. The Protegrity API Playground offers a straightforward way to test Protegrity’s data protection features. The Playground grants you 10,000 API requests after registration to use as you see fit: protecting names, addresses, credit card numbers – or any other data your organization considers secure. This guide will walk you through the setup process and show you sample API calls. And for those who prefer to skip the reading, check out our video guides: Registration & Setup or Using the API.

Choose your language & IDE

The best way to start with the Playground is to use our preconfigured Postman collection: import it into Postman and you are good to go. In this guide we will walk through the login process and show you how to generate requests to the API.

Registration

To register with Protegrity API Playground, fill out the form on the API Playground landing page. The information you provide is collected for user management and analytics. It is protected with Protegrity’s tokenization, ensuring that only authorized team members can view it in clear text. We are drinking our own champagne – it would be unwise not to!

Registration with Protegrity API Playground is straightforward

Once registered, you will receive an email from us. It will include your temporary password and API key. You will need them to authenticate with the Playground.

Welcome Email with your unique API key and password

Login

You will need to log in to start interacting with the Playground. To do so, pass your email and password to the /login endpoint. On a successful login, you will receive a JWT Token. The token, alongside your API Key will be used to authorize the API requests to the Playground going forward.

Login to receive your JWT token

The JWT Token expires every 24 hours. To renew it, go to the /login endpoint, and we will issue a new one.

Environment Setup

Consider saving your JWT Token and the API Key as environment variables for convenience. If you use our preconfigured Postman collection, you can store them in the variables section. This will ensure that they are sent alongside every request and save you some tedious work of providing them with every call.

Setting environment variables in Postman

Now that’s done you’re all set! Let the API Playground be your oyster.

Data Protection Endpoints

Protegrity API Playground exposes a curated selection of endpoints for data protection: you can use them to secure any PII, PCI, or otherwise sensitive information. The predefined endpoints include names, addresses, zip codes, credit card numbers, social security numbers, and more.

Protegrity’s Vaultless Tokenization is renowned for its high configurability. The Playground lets you experiment with some of its flagship capabilities: length-, language-, position-, and case-preservation. This means that if you pass French strings to the API, you will receive a token that carries French characters. Numeric zip codes are length-preserving, meaning that a 5-digit input will produce a 5-digit output. Postcodes, i.e., codes that mix digits and characters, are even more advanced: you will keep their original length, position, and case in the received token. This is a very different approach to encryption, where the cyphertext resulting from the cryptographic function does not match the input domain and requires the developer to change the application to accommodate it.

A full list of available endpoints and their properties is available in the Using the API section. Let’s play around with some of them to give you an idea of what the Playground can offer.

Testing the API

We have hand-picked some protection endpoints that are representative of what you can expect from the Playground – and Protegrity’s platform.

Protecting Names

Most of our clients choose to protect their customers’ names. Let’s construct a request to the /name endpoint to secure the name of the King of England: Charles Mountbatten-Windsor.

The operation should be set to protect: this is how you will instruct the API what to do.

Paste the King’s name in the data and send the request.

Protecting the King’s name

And poof! The King is no longer a known person (in your records). Note that the /name endpoint does not support any text feature preservation (length, case, or position), as there is rarely any business case to do so. You will also notice that something interesting has happened: the separator within the King’s surname was not removed. This is because this tokenization element only acts on letters. Everything else is returned as-is.

You can now pass the protected string into the request and switch the operation to unprotect. This will return the King’s name.

Unprotecting the King’s name

The /name endpoint offers language preservation for German and French characters. To switch it on, provide a dictionary as an option and set it to your preferred language.

Setting French as the dictionary

Protecting Date of Birth

Date of birth is another attribute commonly considered as PII. If you provide it with a date, it will return its secured version in that same format. You can also decide to leave the year in the clear. Often, an entire date of birth is considered a sensitive attribute, however a year on its own is acceptable to be left in the clear. Here’s a sample request issued to /dob endpoint that demonstrates this feature:

Protecting dates of birth

Protecting Credit Card Numbers

Leaving your customer’s credit card numbers unprotected is a sure way to anger auditors, lose customer trust, and get into trouble. CCN is the core piece of data to secure – if you’re unsure what should be your priority, this is it.

When calling the /ccn endpoint, you can decide to protect the entire credit card string or leave the 8-digit BIN in the clear:

Protecting credit card numbers

Protecting multi-type payloads

Now that you have a good grasp of how our API Playground works, you can take it up a notch and protect (and unprotect) multiple data types at once. To do that, use the /multi endpoint. Specify the operation type, the data type, and options for each data point. Refer to the description of each data type (endpoint) to see all options available.

Here’s an example protection request of an address in Paris:

Multi-type request

Summary

The Protegrity API Playground offers a practical and essential entry point to test, evaluate, and refine data protection strategies within a secure environment, allowing teams to see if Protegrity is the right fit for their data privacy needs. Register today to start safeguarding your sensitive data, one API request at a time.

3 - VS Code Guide

The Protegrity API Playground offers an easy way to test Protegrity’s data protection features. It comes with a pre-configured HTTP requests file that can be used in Visual Studio Code with the REST Client extension.

This is an addendum to the Postman guide. Please read that blog post first to learn how to register and how to use the Protegrity API Playground.

Add the REST Client extension

Follow the official documentation on how to add the REST Client extension in Visual Studio Code.

Download the HTTP requests collection

The best way to start with the Protegrity Playground in Visual Studio Code is to use our preconfigured HTTP requests collection file: get it from our Downloads section and open it in Visual Studio Code.

Add your API Key

The HTTP request file starts with the definition of some variables.

@api_token = changeme
@api_url = api.playground.protegrity.com
@api_version = v1
@jwt_token = changeme
@api_auth = auth

These variables will be used to construct the Playground’s URI and populate your authentication information. Change the @api_token to the value you received in your welcome email.

You’ll get the jwt_token only after your first login.

Bonus: Renew your JWT Token automatically

Since the JWT token is only valid for 24 hours and changes with a following login here’s a tip how you can set it automatically after each login.

The first request in the file is the user login. Add two lines to set the @jwt_token variable after each execution of the login request like in the following example:

# @name User_Login
POST https://{{api_url}}/{{api_auth}}/login
Authorization: {{jwt_token}}
Content-Type: application/json
{
  "email": "<YOUR_EMAIL>",
  "password": "<YOUR_PASSWORD>"
}

###
@jwt_token = {{User_Login.response.body.jwt_token}}

Keep your eye on the updates

The API Playground is an evergreen project: we are rolling out updates and new features every couple of months.