> 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/fpe.md).
# FPE
## Format-preserving encrypt a local field
> Encrypts a field using an FPE profile loaded from signed config. The request supplies only ref, profile name, and plaintext; alphabet, length bounds, tweak AAD, FPE version, and bound KID come from config.json. The client ref is echoed in the response.
```json
{"openapi":"3.1.0","info":{"title":"Vectis HTTP API","version":"v1"},"tags":[{"name":"FPE"}],"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}$"},"FpeEncryptInput":{"type":"object","additionalProperties":false,"required":["ref","profile","plaintext"],"properties":{"ref":{"$ref":"#/components/schemas/ClientRef"},"profile":{"$ref":"#/components/schemas/TextField"},"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]+$"},"FpeEncryptOutput":{"type":"object","required":["ref","kid","profile","ciphertext"],"properties":{"ref":{"$ref":"#/components/schemas/ClientRef"},"kid":{"$ref":"#/components/schemas/Kid"},"profile":{"$ref":"#/components/schemas/TextField"},"ciphertext":{"$ref":"#/components/schemas/TextField"},"tag":{"$ref":"#/components/schemas/FpeAuthTag"}}},"FpeAuthTag":{"type":"string","minLength":64,"maxLength":64,"pattern":"^[0-9a-f]{64}$","description":"HMAC-BLAKE2b-256; required for authenticated profiles and prohibited for legacy decrypt. Never nullable."},"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":{"/fpe/encrypt/{kid}":{"post":{"tags":["FPE"],"summary":"Format-preserving encrypt a local field","description":"Encrypts a field using an FPE profile loaded from signed config. The request supplies only ref, profile name, and plaintext; alphabet, length bounds, tweak AAD, FPE version, and bound KID come from config.json. The client ref is echoed in the response.\n","parameters":[{"$ref":"#/components/parameters/Kid"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FpeEncryptInput"}}}},"responses":{"200":{"description":"Format-preserving ciphertext","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FpeEncryptOutput"}}}},"413":{"$ref":"#/components/responses/RequestBodyTooLarge"},"default":{"$ref":"#/components/responses/Error"}}}}}}
```
## Format-preserving encrypt a batch of local fields
> Encrypts a batch with one FPE profile. Each item must include a unique client ref, which is echoed in the corresponding response item. Results preserve request item order. The operation is all-or-nothing: if any item is invalid, the request fails and no partial results are returned.
```json
{"openapi":"3.1.0","info":{"title":"Vectis HTTP API","version":"v1"},"tags":[{"name":"FPE"}],"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}$"},"FpeEncryptBatchInput":{"type":"object","additionalProperties":false,"required":["profile","items"],"properties":{"profile":{"$ref":"#/components/schemas/TextField"},"items":{"type":"array","minItems":1,"maxItems":128,"items":{"type":"object","additionalProperties":false,"required":["ref","plaintext"],"properties":{"ref":{"$ref":"#/components/schemas/ClientRef"},"plaintext":{"$ref":"#/components/schemas/TextField"}}}}}},"TextField":{"type":"string","minLength":1,"pattern":"^[^\\x00-\\x1F\\x7F-\\x9F]+$"},"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."},"FpeEncryptBatchOutput":{"type":"object","required":["kid","profile","items"],"properties":{"kid":{"$ref":"#/components/schemas/Kid"},"profile":{"$ref":"#/components/schemas/TextField"},"items":{"type":"array","items":{"type":"object","required":["ref","ciphertext"],"properties":{"ref":{"$ref":"#/components/schemas/ClientRef"},"ciphertext":{"$ref":"#/components/schemas/TextField"},"tag":{"$ref":"#/components/schemas/FpeAuthTag"}}}}}},"FpeAuthTag":{"type":"string","minLength":64,"maxLength":64,"pattern":"^[0-9a-f]{64}$","description":"HMAC-BLAKE2b-256; required for authenticated profiles and prohibited for legacy decrypt. Never nullable."},"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":{"/fpe/encrypt/batch/{kid}":{"post":{"tags":["FPE"],"summary":"Format-preserving encrypt a batch of local fields","description":"Encrypts a batch with one FPE profile. Each item must include a unique client ref, which is echoed in the corresponding response item. Results preserve request item order. The operation is all-or-nothing: if any item is invalid, the request fails and no partial results are returned.\n","parameters":[{"$ref":"#/components/parameters/Kid"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FpeEncryptBatchInput"}}}},"responses":{"200":{"description":"Batch format-preserving ciphertexts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FpeEncryptBatchOutput"}}}},"413":{"$ref":"#/components/responses/RequestBodyTooLarge"},"default":{"$ref":"#/components/responses/Error"}}}}}}
```
## Encrypt a field with an existing subject seed
> Requires fpe-encrypt, an active KID and a matching stored FPE profile. Seed is opened using its original signed tokenization profile; no token permission is required. No fallback to general keys.
```json
{"openapi":"3.1.0","info":{"title":"Vectis HTTP API","version":"v1"},"tags":[{"name":"FPE"}],"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"}},"Subject":{"name":"subject","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Subject"}}},"schemas":{"Kid":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"},"Subject":{"type":"string","minLength":64,"maxLength":64,"pattern":"^[0-9a-f]{64}$","description":"Profile-scoped HMAC identifier returned by subject creation. Not a user authorization credential."},"FpeEncryptInput":{"type":"object","additionalProperties":false,"required":["ref","profile","plaintext"],"properties":{"ref":{"$ref":"#/components/schemas/ClientRef"},"profile":{"$ref":"#/components/schemas/TextField"},"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]+$"},"FpeSubjectEncryptOutput":{"allOf":[{"$ref":"#/components/schemas/FpeEncryptOutput"},{"type":"object","required":["subject"],"properties":{"subject":{"$ref":"#/components/schemas/Subject"}}}]},"FpeEncryptOutput":{"type":"object","required":["ref","kid","profile","ciphertext"],"properties":{"ref":{"$ref":"#/components/schemas/ClientRef"},"kid":{"$ref":"#/components/schemas/Kid"},"profile":{"$ref":"#/components/schemas/TextField"},"ciphertext":{"$ref":"#/components/schemas/TextField"},"tag":{"$ref":"#/components/schemas/FpeAuthTag"}}},"FpeAuthTag":{"type":"string","minLength":64,"maxLength":64,"pattern":"^[0-9a-f]{64}$","description":"HMAC-BLAKE2b-256; required for authenticated profiles and prohibited for legacy decrypt. Never nullable."},"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":{"/fpe/encrypt/{kid}/subject/{subject}":{"post":{"tags":["FPE"],"summary":"Encrypt a field with an existing subject seed","description":"Requires fpe-encrypt, an active KID and a matching stored FPE profile. Seed is opened using its original signed tokenization profile; no token permission is required. No fallback to general keys.","parameters":[{"$ref":"#/components/parameters/Kid"},{"$ref":"#/components/parameters/Subject"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FpeEncryptInput"}}}},"responses":{"200":{"description":"Ciphertext, subject and optional authentication tag","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FpeSubjectEncryptOutput"}}}},"413":{"$ref":"#/components/responses/RequestBodyTooLarge"},"default":{"$ref":"#/components/responses/Error"}}}}}}
```
## Encrypt a batch with one existing subject seed
> Requires fpe-encrypt, an active KID and a stored FPE profile. Opens seed and prepares keys once for the whole batch. Ordering and all-or-nothing guarantees are unchanged.
```json
{"openapi":"3.1.0","info":{"title":"Vectis HTTP API","version":"v1"},"tags":[{"name":"FPE"}],"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"}},"Subject":{"name":"subject","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Subject"}}},"schemas":{"Kid":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"},"Subject":{"type":"string","minLength":64,"maxLength":64,"pattern":"^[0-9a-f]{64}$","description":"Profile-scoped HMAC identifier returned by subject creation. Not a user authorization credential."},"FpeEncryptBatchInput":{"type":"object","additionalProperties":false,"required":["profile","items"],"properties":{"profile":{"$ref":"#/components/schemas/TextField"},"items":{"type":"array","minItems":1,"maxItems":128,"items":{"type":"object","additionalProperties":false,"required":["ref","plaintext"],"properties":{"ref":{"$ref":"#/components/schemas/ClientRef"},"plaintext":{"$ref":"#/components/schemas/TextField"}}}}}},"TextField":{"type":"string","minLength":1,"pattern":"^[^\\x00-\\x1F\\x7F-\\x9F]+$"},"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."},"FpeSubjectEncryptBatchOutput":{"allOf":[{"$ref":"#/components/schemas/FpeEncryptBatchOutput"},{"type":"object","required":["subject"],"properties":{"subject":{"$ref":"#/components/schemas/Subject"}}}]},"FpeEncryptBatchOutput":{"type":"object","required":["kid","profile","items"],"properties":{"kid":{"$ref":"#/components/schemas/Kid"},"profile":{"$ref":"#/components/schemas/TextField"},"items":{"type":"array","items":{"type":"object","required":["ref","ciphertext"],"properties":{"ref":{"$ref":"#/components/schemas/ClientRef"},"ciphertext":{"$ref":"#/components/schemas/TextField"},"tag":{"$ref":"#/components/schemas/FpeAuthTag"}}}}}},"FpeAuthTag":{"type":"string","minLength":64,"maxLength":64,"pattern":"^[0-9a-f]{64}$","description":"HMAC-BLAKE2b-256; required for authenticated profiles and prohibited for legacy decrypt. Never nullable."},"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":{"/fpe/encrypt/batch/{kid}/subject/{subject}":{"post":{"tags":["FPE"],"summary":"Encrypt a batch with one existing subject seed","description":"Requires fpe-encrypt, an active KID and a stored FPE profile. Opens seed and prepares keys once for the whole batch. Ordering and all-or-nothing guarantees are unchanged.","parameters":[{"$ref":"#/components/parameters/Kid"},{"$ref":"#/components/parameters/Subject"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FpeEncryptBatchInput"}}}},"responses":{"200":{"description":"Complete ciphertext batch with one top-level subject","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FpeSubjectEncryptBatchOutput"}}}},"413":{"$ref":"#/components/responses/RequestBodyTooLarge"},"default":{"$ref":"#/components/responses/Error"}}}}}}
```
## Format-preserving decrypt a local field
> Decrypts a field using an FPE profile loaded from signed config. The KID in the request must match the profile KID. FPE decrypt permits active and retired keys. The client ref is echoed in the response.
```json
{"openapi":"3.1.0","info":{"title":"Vectis HTTP API","version":"v1"},"tags":[{"name":"FPE"}],"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"}},"schemas":{"FpeDecryptInput":{"type":"object","additionalProperties":false,"required":["ref","kid","profile","ciphertext"],"properties":{"ref":{"$ref":"#/components/schemas/ClientRef"},"kid":{"$ref":"#/components/schemas/Kid"},"subject":{"$ref":"#/components/schemas/Subject","description":"Required for stored FPE profiles, prohibited for none; never nullable. One subject applies to all batch items."},"profile":{"$ref":"#/components/schemas/TextField"},"ciphertext":{"$ref":"#/components/schemas/TextField"},"tag":{"$ref":"#/components/schemas/FpeAuthTag"}}},"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."},"Kid":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"},"Subject":{"type":"string","minLength":64,"maxLength":64,"pattern":"^[0-9a-f]{64}$","description":"Profile-scoped HMAC identifier returned by subject creation. Not a user authorization credential."},"TextField":{"type":"string","minLength":1,"pattern":"^[^\\x00-\\x1F\\x7F-\\x9F]+$"},"FpeAuthTag":{"type":"string","minLength":64,"maxLength":64,"pattern":"^[0-9a-f]{64}$","description":"HMAC-BLAKE2b-256; required for authenticated profiles and prohibited for legacy decrypt. Never nullable."},"FpeDecryptOutput":{"type":"object","required":["ref","plaintext"],"properties":{"ref":{"$ref":"#/components/schemas/ClientRef"},"plaintext":{"$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":{"/fpe/decrypt":{"post":{"tags":["FPE"],"summary":"Format-preserving decrypt a local field","description":"Decrypts a field using an FPE profile loaded from signed config. The KID in the request must match the profile KID. FPE decrypt permits active and retired keys. The client ref is echoed in the response.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FpeDecryptInput"}}}},"responses":{"200":{"description":"FPE plaintext","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FpeDecryptOutput"}}}},"413":{"$ref":"#/components/responses/RequestBodyTooLarge"},"default":{"$ref":"#/components/responses/Error"}}}}}}
```
## Format-preserving decrypt a batch of local fields
> Decrypts a batch with one FPE profile. Each item must include a unique client ref, which is echoed in the corresponding response item. Results preserve request item order. The operation is all-or-nothing: if any item is invalid, the request fails and no partial results are returned.
```json
{"openapi":"3.1.0","info":{"title":"Vectis HTTP API","version":"v1"},"tags":[{"name":"FPE"}],"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"}},"schemas":{"FpeDecryptBatchInput":{"type":"object","additionalProperties":false,"required":["kid","profile","items"],"properties":{"kid":{"$ref":"#/components/schemas/Kid"},"subject":{"$ref":"#/components/schemas/Subject","description":"Required for stored FPE profiles, prohibited for none; never nullable. One subject applies to all batch items."},"profile":{"$ref":"#/components/schemas/TextField"},"items":{"type":"array","minItems":1,"maxItems":128,"items":{"type":"object","additionalProperties":false,"required":["ref","ciphertext"],"properties":{"ref":{"$ref":"#/components/schemas/ClientRef"},"ciphertext":{"$ref":"#/components/schemas/TextField"},"tag":{"$ref":"#/components/schemas/FpeAuthTag"}}}}}},"Kid":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"},"Subject":{"type":"string","minLength":64,"maxLength":64,"pattern":"^[0-9a-f]{64}$","description":"Profile-scoped HMAC identifier returned by subject creation. Not a user authorization credential."},"TextField":{"type":"string","minLength":1,"pattern":"^[^\\x00-\\x1F\\x7F-\\x9F]+$"},"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."},"FpeAuthTag":{"type":"string","minLength":64,"maxLength":64,"pattern":"^[0-9a-f]{64}$","description":"HMAC-BLAKE2b-256; required for authenticated profiles and prohibited for legacy decrypt. Never nullable."},"FpeDecryptBatchOutput":{"type":"object","required":["kid","profile","items"],"properties":{"kid":{"$ref":"#/components/schemas/Kid"},"profile":{"$ref":"#/components/schemas/TextField"},"items":{"type":"array","items":{"type":"object","required":["ref","plaintext"],"properties":{"ref":{"$ref":"#/components/schemas/ClientRef"},"plaintext":{"$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":{"/fpe/decrypt/batch":{"post":{"tags":["FPE"],"summary":"Format-preserving decrypt a batch of local fields","description":"Decrypts a batch with one FPE profile. Each item must include a unique client ref, which is echoed in the corresponding response item. Results preserve request item order. The operation is all-or-nothing: if any item is invalid, the request fails and no partial results are returned.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FpeDecryptBatchInput"}}}},"responses":{"200":{"description":"Batch FPE plaintexts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FpeDecryptBatchOutput"}}}},"413":{"$ref":"#/components/responses/RequestBodyTooLarge"},"default":{"$ref":"#/components/responses/Error"}}}}}}
```