Skip to main content
You can import PCI tokens into your Guardian instance. The data must be provided as a PKI-encrypted .tgz archive via SFTP.

​
Step-by-Step Process

1

Step 1 – Request the public key certificate

Contact Hellgate Support to request the public key certificate for token import encryption. Include in your request:
  • Target Cluster ID (the Guardian instance where tokens will be imported)
  • Point of contact for follow-up questions
2

Step 2 – Prepare the import data

Prepare your PCI token data in JSONL format (JSON Lines), where each line is a complete JSON object.
3

Step 3 – Encrypt and package the data

Encrypt your data using the provided Starfish certificate and package it as a .tgz archive.
4

Step 4 – Upload the encrypted archive

Upload the encrypted .tgz archive to a SFTP location.
Verify that the upload completed successfully and that the file is accessible at the specified location.
5

Step 5 – Provide SFTP location

Contact Hellgate Support and provide the SFTP location where the encrypted .tgz archive was made available.

​
Import Data Format

The imported .tgz archive must contain a manifest JSON file and encrypted JSONL records containing the PCI token data. 
import.tgz
├── manifest.json
└── tokens.jsonl.enc

​
Encryption Details

The import uses a hybrid encryption scheme:
  1. AES encryption is used to encrypt the JSONL records file
  2. The AES key is encrypted using RSA-OAEP-256 with Hellgate’s provided certificate’s public key
  3. The encrypted AES key, initialization vector (IV), and authentication tag must be stored in the manifest

​
Manifest Format

The manifest.json file must contain metadata about the import and encryption parameters: 
{
  "version": "1.0",
  "import_id": "<uuid>",
  "created_at": "2025-01-15T10:43:00Z",
  "target_guardian_instance": "my-cluster-id.on-hellgate.cloud",
  "encryption": {
    "algorithm": "RSA-OAEP-256",
    "recipient": {
      "subject": "O=Starfish GmbH & Co. KG, C=DE",
      "issuer": "CN=DigiCert TLS RSA4096 Root G5, O=DigiCert Inc, C=US",
      "serial": "0f:4a:2b:...",
      "fingerprint": "sha256:3c:5d:8e:..."
    },
    "encrypted_key": "<base64>",
    "iv": "<base64>",
    "tag": "<base64>"
  },
  "content": {
    "record_count": 142857,
    "checksum": "sha256:<hex>"
  }
}
FieldDescription
versionImport format version
import_idUnique identifier for this import
created_atTimestamp when the import was created
target_guardian_instanceThe target Guardian instance identifier
encryption.algorithmThe RSA encryption algorithm used (RSA-OAEP-256)
encryption.recipient.subjectCertificate subject (organization identity)
encryption.recipient.issuerCertificate issuer (CA)
encryption.recipient.serialCertificate serial number (hex)
encryption.recipient.fingerprintCertificate fingerprint (SHA-256)
encryption.encrypted_keyAES key encrypted with Starfish’s public key
encryption.ivInitialization vector for AES encryption
encryption.tagAuthentication tag for AES-GCM
content.record_countTotal number of records in the import
content.checksumSHA-256 checksum of the decrypted JSONL content

​
Record Format

The tokens.jsonl.enc file must contain encrypted JSONL (JSON Lines) data. After decryption, each line is a JSON object representing a PCI token record. Each record must follow this structure: 
{
  "card": {
    "cardholder_name": "John Doe",
    "expiry_month": 12,
    "expiry_year": 2025,
    "account_number": "4111111111111111",
    "scheme": "visa"
  },
  "metadata": {
    "my_key_one": "my_value_one",
    "my_key_two": "my_value_two"
  }
}

​
Common Issues & Troubleshooting

Contact Hellgate Support with your import request details. The certificate will be provided in PEM format.
Ensure your JSONL records follow the exact format specified. Each line must be a valid JSON object with the required card fields.
Import times vary based on the volume of data. Starfish will notify you once the import is complete or if any issues arise.
Contact Hellgate Support immediately. You may need to re-upload the archive or provide an alternative delivery method.