PII Masking

Overview

The Minded platform provides built-in protection for Personally Identifiable Information (PII) through an advanced masking mechanism. This feature ensures that sensitive data remains secure throughout your application's lifecycle while preserving the contextual integrity of your business logic.

How to Use PII Masking

Step 1: Configure PII Masking in the Minded Platform

To enable PII masking, go to the agent configuration panel and toggle "Enable PII Masking". Then, configure the masking behavior according to your needs by specifying:

Entity Types: Define which data entities should be treated as PII. Any entity that requires masking must be explicitly listed.
Detection Model: By default, Minded uses OpenAI's GPT-4.1-mini for PII detection. Optionally, you can provide a custom Azure OpenAI deployment. Be sure to include the corresponding API key in the environment's secrets.
TTL Settings: TTL (Time-to-Live) determines how long masked data is stored for a specific sessionId. The default TTL is 14 hours.
Trigger SessionId Field: Specify the property name in your incoming webhook payload that contains the session ID. This field is used to identify and group PII data per session. It must be a single word with no special characters (only letters, numbers, and underscores allowed).

Once enabled, PII masking is automatically applied at critical points within the platform:

All webhook payloads are masked upon receipt.
App integrations undergo automatic unmasking before requests and re-masking after responses.

Step 2: Use PII Masking via the Minded SDK

Minded provides automatic PII masking capabilities for HTTP requests within your agent workflows. When a trigger is received with a sessionId, the PII masking functionality is automatically initialized and made available to your custom code through the agent's PII gateway.

PII Gateway for HTTP Requests

The PII gateway enables secure HTTP communication by automatically handling PII masking/unmasking for your API calls. It provides a complete HTTP client interface similar to popular libraries like Axios, supporting all common HTTP methods.

The PII masking gateway ensures:

Automatic Unmasking: Requests are automatically unmasked before being sent to external APIs
Secure Routing: All requests are routed through Minded's secure gateway infrastructure
Response Masking: API responses are automatically masked before being returned to your agent
Session Isolation: PII data is properly isolated per session using the sessionId
Error Handling: Comprehensive error handling for network issues and API failures

Note: API error responses are not masked. The PII gateway requires a valid sessionId to function properly.

Available HTTP Methods

The PII gateway supports all standard HTTP methods:

// GET request
const userData = await agent.piiGateway.get(sessionId, 'https://api.example.com/user/123');

// POST request
const createResult = await agent.piiGateway.post(sessionId, 'https://api.example.com/users', {
  name: 'John Doe',
  email: '[email protected]',
});

// PUT request
const updateResult = await agent.piiGateway.put(sessionId, 'https://api.example.com/user/123', {
  email: '[email protected]',
});

// DELETE request
const deleteResult = await agent.piiGateway.delete(sessionId, 'https://api.example.com/user/123');

// PATCH request
const patchResult = await agent.piiGateway.patch(sessionId, 'https://api.example.com/user/123', {
  email: '[email protected]',
});

Example Usage in Tools

// POST request example - within a custom tool
import { Tool } from '@minded-ai/mindedjs';
import { logger } from '@minded-ai/mindedjs';

const modelParams = z.object({
  prev: z.string().describe('The email to update'),
  new: z.string().describe('The new email address'),
});

const updateEmailTool: Tool<any, any> = {
  name: 'updateEmail',
  description: 'Update the email',
  input: modelParams,
  execute: async ({ input, state, agent }) => {
    try {
      logger.info('Updating email via PII gateway', {
        sessionId: state.sessionId,
      });

      const response = await agent.piiGateway.post(state.sessionId, 'https://www.acme.com/update_email', {
        oldEmail: input.prev,
        newEmail: input.new,
      });

      logger.info('Email update successful', {
        sessionId: state.sessionId,
        status: response.status,
      });

      return {
        result: 'Email updated successfully',
        state: {
          memory: {
            emailUpdated: true,
            lastEmailUpdate: new Date().toISOString(),
          },
        },
      };
    } catch (err) {
      logger.error({
        message: 'Email update failed',
        sessionId: state.sessionId,
        err,
      });
      throw err;
    }
  },
};

Request Configuration

You can also pass additional configuration options:

const response = await agent.piiGateway.post(
  sessionId,
  'https://api.example.com/data',
  { data: 'example' },
  {
    headers: {
      Authorization: 'Bearer token',
      'Content-Type': 'application/json',
    },
    params: {
      version: 'v1',
      format: 'json',
    },
  },
);

How It Works

Trigger Received: When your agent receives a trigger with a sessionId, the PII masking gateway is automatically initialized and available via agent.piiGateway
Session Binding: The PII gateway is bound to the specific session context, ensuring proper PII isolation
Request Processing: When you make HTTP requests through the gateway:
- Request data is automatically unmasked using session-specific mappings
- The request is sent to the target API with real, unmasked data
- The response is received and automatically masked before being returned
Error Handling: Network errors and API errors are properly handled and logged

How PII Masking Works

Input Processing

The masking workflow begins as data enters the Minded platform:

The platform receives input (e.g. JSON object or string) tagged with a unique sessionId.
PII entities are identified using the configured detection model.
Detected entities are replaced with structured placeholders such as:
- <PERSON1>, <PERSON2> for names
- <PHONE1> for phone numbers
- <ADDRESS1>, <ADDRESS2> for addresses
- Other entity types as defined in your configuration
A secure internal PII database (PII-DB) manages the mapping:
- Each sessionId has its own isolated mapping store
- Example mapping:
  "Kate" → <PERSON1> "Josh Wildon" → <PERSON2>
- Consistent masking/unmasking is maintained throughout the session
- Data is automatically purged from the PII-DB based on TTL settings

Session ID Configuration

The Trigger SessionId Field setting in the UI specifies which field in your webhook payload contains the session identifier:

Field Name: Must be a valid property name (letters, numbers, underscores only)
Examples: sessionId, session_id, conversationId, userId
Purpose: Groups all PII data for a specific user session together
Requirements:
- Single word identifier
- No special characters except underscores
- Must exist in every webhook payload

Example webhook payload where we set Trigger SessionId Field to webhookId:

{
  "webhookId": "user_12345_conversation_67890",
  "customerName": "John Doe",
  "email": "[email protected]",
  "orderDetails": "Need help with order #ABC123"
}

Mask Consistency

The platform guarantees deterministic masking within a session:

Each unique entity always receives the same placeholder
New placeholders are generated only for previously unseen entities
Cross-reference logic maintains consistent relationships between data
TTL should be aligned with your agent's session lifecycle for optimal performance

Logging and Storage

All logs within the platform are written only with masked data
Raw, unmasked data is never logged

PreviousSecrets NextOperator

Last updated 15 days ago