Data Classification & Masking Model

Summary

Keymate's data classification and masking model defines how the platform transforms API responses based on data sensitivity. When a DSAC policy determines that a user lacks clearance for specific data fields, the masking model controls the transformation — replacing values with masked representations, omitting fields entirely, or blocking the response. This model describes the classification taxonomy, masking strategies, and enforcement behavior that execute after DSAC policy evaluation.

Why It Exists

DSAC policies produce access decisions at the field level, but the decision alone does not define what happens to restricted data. Should a restricted salary field display as ****, disappear from the response, or prevent the entire API call? The masking model answers these questions by providing configurable transformation strategies. This separation of concerns keeps DSAC policies focused on access decisions while the masking model handles response transformation.

Where It Fits in Keymate

The masking model executes after DSAC policies evaluate within the authorization model. DSAC determines which fields the user can access; the masking model transforms the response accordingly. Classification labels attach to resources and scopes. The user's clearance level comes from identity attributes. The gateway enforcement layer applies masking transformations before returning the response to the client.

Boundaries

This page covers classification taxonomy, masking strategies, and response transformation. It does not cover:

• Classification-based access decisions — see DSAC
• General authorization model — see Authorization Model
• Attribute definitions and scoping — see Identity Attributes & Claims
• Policy evaluation pipeline — see Policy Evaluation Model

How It Works

Classification Taxonomy

Organizations define a classification taxonomy that categorizes data sensitivity levels. A typical taxonomy includes:

Level	Description	Example Fields
Public	Open information with no access restriction	Name, public contact info
Internal	Organization-internal data	Employee ID, department
Confidential	Sensitive business data	Salary, performance rating
Restricted	Highly sensitive data requiring explicit clearance	National identifier, financial account numbers

The taxonomy is configurable per Tenant. Each Tenant defines the classification levels that match its regulatory and organizational requirements.

Field Classification

Administrators assign classification labels to individual fields within a resource definition. A single resource can contain fields with different classification levels. For example, an employee record resource might classify:

• name → Public
• email → Internal
• salary → Confidential
• nationalId → Restricted

Classification labels persist as metadata on the resource definition and apply to all instances of that resource.

Masking Strategies

When a field exceeds the user's clearance level, the platform applies one of several masking strategies:

• Value masking — the field appears in the response, but its value is replaced with a masked representation. Common patterns include full masking (****), partial masking (showing the first or last characters: J*** D**), and type-preserving masking (replacing digits with zeros, letters with asterisks).
• Field omission — the field is removed from the response entirely. The client does not receive the field key or any indication that the field exists.
• Null replacement — the field appears in the response with a null value. This preserves the response schema while hiding the actual value.
• Request denial — the entire request fails if any field in the response exceeds the user's clearance. Use this strategy for resources where partial data disclosure is unacceptable.

The strategy is configurable per classification level and per resource, allowing different responses for different sensitivity thresholds.

Enforcement Flow

The masking model executes in the following sequence:

1. The request passes endpoint-level authorization (RBAC, ABAC, or other models)
2. The platform retrieves the response data from the backend service
3. DSAC policies evaluate each field's classification against the user's clearance level
4. For fields that exceed the user's clearance, the masking model applies the configured strategy
5. The transformed response returns to the client

This post-evaluation transformation ensures that the client receives a response that respects data classification without requiring the backend service to implement masking logic.

Classification Inheritance

Classification labels can inherit through resource hierarchies:

• A parent resource's classification applies as the minimum for all child resources unless a child specifies a higher classification
• Fields without explicit classification inherit the resource-level default
• Explicit field-level classification overrides the resource-level default

This inheritance model reduces classification management for resources with uniform sensitivity while allowing field-level overrides where needed.

Diagram

Example Scenario

Scenario

An HR API returns employee records with classified fields. A department manager with "Internal" clearance requests an employee record. The record contains fields classified as Public (name), Internal (email, department), Confidential (salary), and Restricted (national identifier). The masking configuration uses value masking for Confidential fields and field omission for Restricted fields.

Input

• Actor: Department manager with "Internal" clearance
• Resource: Employee record with mixed field classifications
• Action: Read employee record
• Context: Masking strategy: value masking for Confidential, field omission for Restricted

Expected Outcome

• Applied — The response includes name (Public — full value), email and department (Internal — full value, within clearance), salary displayed as **** (Confidential — value masked), and nationalId omitted entirely (Restricted — field removed). The manager receives a complete response structure minus the restricted field, with confidential values masked.
• Why: DSAC evaluates each field against the manager's "Internal" clearance. Fields at or below "Internal" return full values. The "Confidential" salary field exceeds clearance and receives value masking. The "Restricted" national identifier exceeds clearance further and is omitted per the configured strategy.

Common Misunderstandings

• "Masking happens at the database level" — No. The masking model transforms API responses after data retrieval. The backend service returns full data, and the platform applies masking before delivering the response to the client.

• "All masked fields use the same masking strategy" — No. Different classification levels can use different strategies. Confidential fields might use value masking while Restricted fields use field omission.

• "The client can detect which fields were masked versus which are genuinely null" — With null replacement, the client cannot distinguish between a masked field and a legitimately null field. Use value masking (e.g., ****) when the client needs to know a value exists but cannot see it.

warning

Ensure that masked responses do not leak classified data through side channels. For example, if the response includes a record count that changes based on classification, a user might infer the existence of restricted records by comparing counts at different clearance levels.

Design Notes / Best Practices

• Choose masking strategies that match the use case. Value masking works for UI display where the user needs to know a value exists. Field omission works for API consumers that should not process restricted fields at all.
• Define classification labels at the schema level and override at the field level only when necessary. This reduces management overhead and ensures consistent classification across resources.
• Test masking configurations with representative data before deploying to production. Verify that masked responses maintain the expected schema and do not break downstream consumers that depend on specific field presence.

tip

When building APIs that will use data classification, design response schemas that degrade gracefully when fields are omitted or masked. Use optional fields in API contracts and document which fields may be subject to classification-based masking.

Related Use Cases

• Masking salary information for managers without finance clearance
• Omitting national identifier fields from standard API responses
• Applying different masking strategies per classification level
• Enforcing field-level data protection for regulatory compliance

Related Docs

DSAC

Classification-based access decisions that trigger masking

Authorization Model

Multi-model framework that DSAC and masking operate within

Identity Attributes & Claims

User clearance levels that drive masking decisions

Resources & Scopes

Resource definitions that carry classification labels