> For the complete documentation index, see [llms.txt](https://vectis.liesware.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://vectis.liesware.com/masking.md).

# Masking

## Mask a field value for controlled display

> Applies a signed masking profile to a plaintext value. Masking is display-only; it does not encrypt, tokenize, persist, or derive keys. The profile KID is used for permission and lifecycle checks.<br>

```json
{"openapi":"3.1.0","info":{"title":"Vectis HTTP API","version":"v1"},"tags":[{"name":"Masking"}],"servers":[{"url":"http://127.0.0.1:3000","description":"Local default server over HTTP"},{"url":"https://127.0.0.1:3000","description":"Local HTTPS server when VECTIS_MODE=prod"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key"}},"parameters":{"Kid":{"name":"kid","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Kid"}}},"schemas":{"Kid":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"},"MaskInput":{"type":"object","additionalProperties":false,"required":["ref","profile","plaintext"],"properties":{"ref":{"$ref":"#/components/schemas/ClientRef"},"profile":{"$ref":"#/components/schemas/AadSafeText"},"plaintext":{"$ref":"#/components/schemas/TextField"}}},"ClientRef":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[^\\x00-\\x1F\\x7F-\\x9F]+$","description":"Client-defined correlation reference. Echoed in FPE, tokenization, MAC, commitment, blind-index, and masking responses; not used for cryptographic derivation, storage lookup, audit, or metrics."},"AadSafeText":{"type":"string","minLength":1,"pattern":"^[^\\x00-\\x1F\\x7F-\\x9F;=]+$","description":"Text safe to embed in a key=value;... AAD string (no ';' or '=')."},"TextField":{"type":"string","minLength":1,"pattern":"^[^\\x00-\\x1F\\x7F-\\x9F]+$"},"MaskOutput":{"type":"object","required":["ref","kid","profile","masked"],"properties":{"ref":{"$ref":"#/components/schemas/ClientRef"},"kid":{"$ref":"#/components/schemas/Kid"},"profile":{"$ref":"#/components/schemas/AadSafeText"},"masked":{"$ref":"#/components/schemas/TextField"}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"$ref":"#/components/schemas/TextField"}}}},"responses":{"RequestBodyTooLarge":{"description":"Request body exceeds the internal 2 MiB limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Error":{"description":"Public error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/mask/{kid}":{"post":{"tags":["Masking"],"summary":"Mask a field value for controlled display","description":"Applies a signed masking profile to a plaintext value. Masking is display-only; it does not encrypt, tokenize, persist, or derive keys. The profile KID is used for permission and lifecycle checks.\n","parameters":[{"$ref":"#/components/parameters/Kid"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MaskInput"}}}},"responses":{"200":{"description":"Masked value","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MaskOutput"}}}},"413":{"$ref":"#/components/responses/RequestBodyTooLarge"},"default":{"$ref":"#/components/responses/Error"}}}}}}
```

## Mask field values as an all-or-nothing batch

> Applies one signed masking profile to a batch. Each item must include a unique client ref. Any validation or execution error fails the whole batch and returns no partial items.<br>

```json
{"openapi":"3.1.0","info":{"title":"Vectis HTTP API","version":"v1"},"tags":[{"name":"Masking"}],"servers":[{"url":"http://127.0.0.1:3000","description":"Local default server over HTTP"},{"url":"https://127.0.0.1:3000","description":"Local HTTPS server when VECTIS_MODE=prod"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key"}},"parameters":{"Kid":{"name":"kid","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Kid"}}},"schemas":{"Kid":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"},"MaskBatchInput":{"type":"object","additionalProperties":false,"required":["profile","items"],"properties":{"profile":{"$ref":"#/components/schemas/AadSafeText"},"items":{"type":"array","minItems":1,"maxItems":128,"items":{"$ref":"#/components/schemas/MaskBatchItemInput"}}}},"AadSafeText":{"type":"string","minLength":1,"pattern":"^[^\\x00-\\x1F\\x7F-\\x9F;=]+$","description":"Text safe to embed in a key=value;... AAD string (no ';' or '=')."},"MaskBatchItemInput":{"type":"object","additionalProperties":false,"required":["ref","plaintext"],"properties":{"ref":{"$ref":"#/components/schemas/ClientRef"},"plaintext":{"$ref":"#/components/schemas/TextField"}}},"ClientRef":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[^\\x00-\\x1F\\x7F-\\x9F]+$","description":"Client-defined correlation reference. Echoed in FPE, tokenization, MAC, commitment, blind-index, and masking responses; not used for cryptographic derivation, storage lookup, audit, or metrics."},"TextField":{"type":"string","minLength":1,"pattern":"^[^\\x00-\\x1F\\x7F-\\x9F]+$"},"MaskBatchOutput":{"type":"object","required":["kid","profile","items"],"properties":{"kid":{"$ref":"#/components/schemas/Kid"},"profile":{"$ref":"#/components/schemas/AadSafeText"},"items":{"type":"array","items":{"$ref":"#/components/schemas/MaskBatchOutputItem"}}}},"MaskBatchOutputItem":{"type":"object","required":["ref","masked"],"properties":{"ref":{"$ref":"#/components/schemas/ClientRef"},"masked":{"$ref":"#/components/schemas/TextField"}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"$ref":"#/components/schemas/TextField"}}}},"responses":{"RequestBodyTooLarge":{"description":"Request body exceeds the internal 2 MiB limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Error":{"description":"Public error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/mask/batch/{kid}":{"post":{"tags":["Masking"],"summary":"Mask field values as an all-or-nothing batch","description":"Applies one signed masking profile to a batch. Each item must include a unique client ref. Any validation or execution error fails the whole batch and returns no partial items.\n","parameters":[{"$ref":"#/components/parameters/Kid"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MaskBatchInput"}}}},"responses":{"200":{"description":"Masked values","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MaskBatchOutput"}}}},"413":{"$ref":"#/components/responses/RequestBodyTooLarge"},"default":{"$ref":"#/components/responses/Error"}}}}}}
```