PCI Vault Logo
Getting Started

This guide will take you through the PCI Vault basics. It is slightly technical, but if you are not technical you should still be able to follow it. It is less intimidating than it looks.

The simplest way to get started with the vault is with our API documentation which allows you to interface with the API directly from the browser.

If you don't have API credentials yet, then register and get API access now.

Before you Start: Verify Your Login Details (Optional)

Find the "Get User and Version Information" section in the API documentation and click on "Try Me!". Your browser should display a pop-up asking for your username and password. Enter the username and password you provided during registration.

In the "Responses" section you should see a new response containing something similar to this:

{
  "user": "your_username",
  "api_version": "1.8.1",
  "backwards_compatibility": "v1",
  "environment": "production"
}

Please confirm that the username in the "user": "your_username" line is your actual username, if it is correct, you have successfully verified your login details.

Most browsers will store the username and password, so you won't have to provide it on every request. If you access our API programmatically, you will have to provide the username and password with every request using Basic Auth.

Step 1: Add Your Own Key

A key is the private key part of a public-key cryptography key pair. This is the same cryptography used by PGP, SSH, Bitcoin, etc. We store the private key on our database. You (and only you) have access to the passphrase needed to unlock the private key. You can think of this setup as a key with 2 parts, where both parts are needed to access the data it locked. You have one part (the passphrase) and PCI Vault has the other part.

You only need one key to encrypt all of your data. However, we recommend using a new key for every few hundred data items to make admin easier.

To generate a key, you will need to provide us with a "user" and a passphrase. The "user" is for identifying the key and we need the passphrase to generate the private key. We do not store the passphrase and do not have access to it. It is your responsibility to store the passphrase and keep it safe. If you lose your passphrase, the key will become unusable and all data locked with it will be locked forever.

You can create a key with the "Create a Key" endpoint. Specify the user and passphrase in the request body using the input fields for user and passphrase. Then click on the "Try Me!" button.

If everything went well, the vault will respond like this:

{
  "passphrase": "ALongAndVerySecretPassphraseThatIsSuperSecure",
  "user": "test-user"
}

The key will be active immediately. Make sure to store the passphrase somewhere safe!

Step 2: Store Some Data in the Vault

Use the "Encrypt and Tokenize Data" endpoint to store data in the vault. You will need to provide the user and passphrase so that we can unlock the correct key. We recommend using a meaningful reference to assist with lookups. The actual data to store must be given as a valid JSON object like this:

{
  "card_expiry": "06-2025",
  "card_holder": "J DOE",
  "card_number": "4111 1111 1111 1111"
}

PCI Vault will encrypt your data, store it and respond with a token. The response will be similar to this:

{
  "token": "753981707e3b4bf81a6d495f063461ce7b70fdb4c12f0dd760e1d31ebbc7c8cf",
  "user": "test-user",
  "reference": "SomethingMeaningfulToYou"
}

We recommend that you store all 3 of these values somewhere accessible. You will need all three (along with the passphrase!) to retrieve the data from the vault again.

Step 3: Retrieve Data from the Vault

To retrieve data from the vault use the

"Decrypt or List Tokenized Data" endpoint. You will need to provide

  • the token generated by the vault previously,
  • the reference that the data was stored under,
  • and the key and passphrase used to encrypt and store the data.

If you provided the correct information, the vault will decrypt the data and send the decrypted data in the response:

{
  "card_expiry": "06-2025",
  "card_holder": "J DOE",
  "card_number": "4111 1111 1111 1111"
}

Step 4: Start Developing!

You now successfully stored and retrieved data from the vault. This guide introduced you to some key concepts which you can use to manually store and retrieve as many cards as you want. To really leverage the value that PCI Vault provides, it is best to write software to interface with our API.

The next step is to Capture Data in a way where all PCI compliance is handled for you.