Welcome to the protegrity-ai-developer-java repository, part of the Protegrity AI Developer Edition suite. This repository provides the Java SDK for integrating Protegrity's Data Discovery and Protection APIs into GenAI and traditional applications. Customize, compile, and use the modules as per your requirement.

💡Note: This SDK should be built and used only if you intend to modify the source code or default behavior.

1. Overview
   • Why This Matters
2. Repository Structure
3. Features
   • Protegrity AI Developer Edition Module
   • Application Protector Java Module
4. Getting Started
   • Prerequisites
5. Protegrity AI Developer Edition Module
   • Usage Examples
     • Find and Redact
     • Find and Protect
     • Find and Unprotect
6. Application Protector Java Module
   • Usage Examples
     • Protect & Unprotect Data
7. Documentation
8. Sample Use Case
9. License

This repository contains two powerful modules designed to handle different aspects of data protection:

• protegrity-ai-developer-edition - Focuses on data discovery, classification, and redaction of Personally Identifiable Information (PII) in unstructured text.
• application-protector-java - Provides comprehensive data protection and unprotection capabilities for structured data.

Sensitive data shows up in more places than expected, such as logs, payloads, prompts, training sets, and unstructured text. This Java SDK provides tools to find and protect that data using tokenization, masking, and discovery. The data might be in an AI pipeline or a local application. No infrastructure, no UI, just code.

• Developer-first experience: Open APIs, sample apps, and modular design make it easy to embed data discovery and protection into any Java project.

• Accelerate innovation: Prototype and validate data discovery and protection strategies in a lightweight, containerized sandbox.

• Enable responsible AI: Protect sensitive information in training data, prompts, and outputs for GenAI and machine learning workflows.

• Simplify compliance: Meet regulatory requirements for data privacy with built-in detection and protection capabilities.

├── LICENSE
├── README.md
├── pom.xml                                    # Parent POM
├── mvnw, mvnw.cmd                            # Maven wrapper
├── application-protector-java/               # Core SDK module
│   ├── pom.xml
│   ├── src/
│   │   ├── main/java/com/protegrity/ap/java/
│   │   └── test/
│   └── target/
│       └── ApplicationProtectorJava-1.1.0.jar
├── protegrity-ai-developer-edition/            # Developer utilities module
│   ├── pom.xml
│   ├── src/
│   │   ├── main/java/com/protegrity/devedition/
│   │   └── test/
└── integration-tests/                        # Cucumber BDD tests
    ├── pom.xml
    ├── src/
    │   └── test/
    │       ├── java/com/protegrity/
    │       └── resources/features/
    └── README.md

• Git
• Java 11 or later
• Maven 3.6+ or use the included Maven wrapper

No additional prerequisites required beyond the common ones.

• In addition to the common prerequisites, Application Protector Java requires API Key, Email, and Password

  Obtaining Credentials

  AI Developer Edition Portal Registration

  • Visit https://www.protegrity.com/developers/dev-edition-api.
  • Register for a developer account.
  • Open your inbox to view the email with your API key and password.

1. Clone the repository.

   git clone https://github.com/Protegrity-AI-Developer-Edition/protegrity-ai-developer-java.git

2. Navigate to the protegrity-ai-developer-java directory

3. Build and install the modules by running the following command from the root directory of the repository.

   ./mvnw clean install

   The build completes and the success message is displayed. The following artifacts are created:

   • application-protector-java/target/ApplicationProtectorJava-1.1.0.jar (fat JAR with dependencies)
   • protegrity-ai-developer-edition/target/ProtegrityAiDeveloperJava-1.1.0.jar (fat JAR with dependencies)
   • Maven artifacts in your local repository (.m2/repository)

4. To run integration tests (optional):

   ./mvnw clean verify -DskipITs=false

💡Note: Ensure that the Protegrity AI Developer Edition is set up and running before using this module. For setup instructions, refer to the Protegrity AI Developer Edition readme or the Protegrity AI Developer Edition documentation.

The following examples demonstrate common workflows using the Protegrity AI Developer Edition Java module. Each example shows how to configure the module, invoke Data Discovery, and apply a processing method such as redaction or tokenization to sensitive data found in plain text inputs.

This example scans input text for sensitive entities such as names and social security numbers using Data Discovery. It then replaces the detected values with a configurable masking character to produce a redacted output.

package com.protegrity.devedition.samples;

import com.protegrity.devedition.utils.Discover;
import com.protegrity.devedition.utils.PiiProcessing;
import com.protegrity.devedition.utils.Config;
import com.fasterxml.jackson.databind.JsonNode;
import java.util.List;
import java.util.HashMap;
import java.util.Map;

public class FindAndRedactExample {
    public static void main(String[] args) throws Exception {
        // Configure
        Map<String, String> entityMap = new HashMap<>();
        entityMap.put("PERSON", "NAME");
        entityMap.put("SOCIAL_SECURITY_ID", "SSN");
        Config.setNamedEntityMap(entityMap);
        Config.setMaskingChar("#");
        Config.setMethod("redact");
        
        // Discover and redact
        String inputText = "John Doe's SSN is 123-45-6789.";
        JsonNode discoveryResult = Discover.discover(inputText);
        List<PiiProcessing.EntitySpan> entities = PiiProcessing.collectEntitySpans(discoveryResult, inputText);
        String outputText = PiiProcessing.redactData(entities, inputText);
        
        System.out.println("Redacted: " + outputText);
    }
}

Set the credentials as environment variables for running Protection examples:

export DEV_EDITION_EMAIL='<email_used_for_registration>'
export DEV_EDITION_PASSWORD='<Password_provided_in_email>'
export DEV_EDITION_API_KEY='<API_key_provided_in_email>'

This example uses Data Discovery to identify sensitive entities in the input text. It then applies tokenization using the Protegrity API Service to replace each detected value with a format-preserving token that can be reversed with the appropriate permissions.

package com.protegrity.devedition.samples;

import java.util.HashMap;
import java.util.List;
import java.util.Map;

import com.fasterxml.jackson.databind.JsonNode;
import com.protegrity.devedition.utils.Config;
import com.protegrity.devedition.utils.Discover;
import com.protegrity.devedition.utils.PiiProcessing;

public class FindAndProtectExample {
    public static void main(String[] args) throws Exception {
        
        // Configure
        Map<String, String> entityMap = new HashMap<>();
        entityMap.put("PERSON", "NAME");
        entityMap.put("SOCIAL_SECURITY_ID", "SSN");
        Config.setNamedEntityMap(entityMap);

        // Discover PII
        String inputText = "John Doe's SSN is 123-45-6789.";
        JsonNode discoveryResult = Discover.discover(inputText);
        List<PiiProcessing.EntitySpan> entities = PiiProcessing.collectEntitySpans(discoveryResult, inputText);
        
        // Protect data
        String outputText = PiiProcessing.protectData(entities, inputText);
        
        System.out.println("Protected: " + outputText);
    }
}

This example takes previously tokenized text, where sensitive values have been replaced with format-preserving tokens enclosed in entity tags, and reverses the protection to restore the original plaintext values. It is subject to the caller's role-based permissions.

package com.protegrity.devedition.samples;

import com.protegrity.devedition.utils.PiiProcessing;

public class FindAndUnprotectExample {
    public static void main(String[] args) throws Exception {
        
        // Protected text from FindAndProtectExample
        String protectedText = "[PERSON]7ro8 lfU'I[/PERSON] SSN is [SOCIAL_SECURITY_ID]616-16-2210[/SOCIAL_SECURITY_ID].";
        
        // Unprotect
        String outputText = PiiProcessing.unprotectData(protectedText);
        
        System.out.println("Unprotected: " + outputText);
    }
}

The Application Protector Java module provides direct access to Protegrity's tokenization and detokenization capabilities. Use this module when you already know which fields contain sensitive data and want to apply protection or reverse it programmatically through the API Service.

Set the credentials as environment variables:

export DEV_EDITION_EMAIL='<email_used_for_registration>'
export DEV_EDITION_PASSWORD='<Password_provided_in_email>'
export DEV_EDITION_API_KEY='<API_key_provided_in_email>'

This example demonstrates how to tokenize and detokenize an array of sensitive values, such as credit card numbers using the Application Protector API. It connects to the API Service, applies protection using a specified data element and user role, then reverses the operation to retrieve the original values.

package com.protegrity.devedition.samples;

import com.protegrity.ap.java.*;
import java.util.Arrays;

public class BulkProtectExample {
    public static void main(String[] args) {
        try {
            Protector protector = Protector.getProtector();
            String userName = "superuser";
            String dataElement = "ccn";
            String[] data = {"5555555555554444", "378282246310005", "4111111111111111"};
            
            SessionObject session = protector.createSession(userName);
            System.out.println("Original Data: " + Arrays.toString(data));

            // Protect bulk
            String[] protectedData = new String[data.length];
            protector.protect(session, dataElement, data, protectedData);
            System.out.println("Protected Data: " + Arrays.toString(protectedData));
            
            // Unprotect bulk
            String[] unprotectedData = new String[data.length];
            protector.unprotect(session, dataElement, protectedData, unprotectedData);
            System.out.println("Unprotected Data: " + Arrays.toString(unprotectedData));
            
        } catch (ProtectorException e) {
            e.printStackTrace();
        }
    }
}

💡Note: You do not need Protegrity AI Developer Edition running before executing just the Application Protector Java Module.

The same Protector code works with your own Cloud Protect deployment, just with the endpoint and auth mode change. Settings are resolved in the order environment variable → ~/.protegrity/config.yaml → built-in default (override the file path with PTY_CONFIG_FILE).

export PTY_CP_HOST=https://<your-cloud-protect-host>/pty
export PTY_AUTH_MODE=bearer_token            # or cognito, aws_iam, mtls, none
export PTY_STATIC_TOKEN=<your-jwt>           # for bearer_token mode (or fetch via OAuth2: PTY_TOKEN_ENDPOINT + PTY_CLIENT_ID + PTY_CLIENT_SECRET)

Or, equivalently, in ~/.protegrity/config.yaml:

protect_host: https://cp.example.com/pty
auth_mode: bearer_token
request_timeout: 30
max_retries: 3
# static_token: eyJhbGciOi...   # see security note below

🔒 Secret keys (static_token, client_secret) are read from the YAML file only when the file is chmod 600 (owner-only - the same rule SSH and ~/.pgpass enforce). Loose permissions cause the secret keys to be dropped at load time with an slf4j WARN; non-secret keys still load normally. The POSIX permission check is skipped on Windows.

• Protegrity AI Developer Edition documentation
• For API reference and tutorials, visit Developer Portal
• For more information about Data Discovery, refer to the Data Discovery documentation.
• For more information about Semantic Guardrails, refer to the Semantic Guardrails documentation.
• For more information about Application Protector Java, refer to the Application Protector Java documentation.

Use this SDK to build GenAI applications like chatbots that:

• Detect Personally Identifiable Information (PII) in prompts using the classifier
• Protect, Redact, or Mask sensitive data before processing
• Protect and Unprotect structured sensitive data

See LICENSE for terms and conditions.