> 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/tokenization.md).
# Tokenization
## Create a stored subject seed
> Requires subject-create for this KID, an active key and a matching stored tokenization profile. The name is not stored. Idempotent retries return 200 with the same ID and never replace or repair the seed. Caller names are not normalized. The subject identifier is deterministic for the same KID, profile and exact name; the seed is random and is never returned. Retain the returned identifier for subject-bound token operations. No ref is required.
```json
{"openapi":"3.1.0","info":{"title":"Vectis HTTP API","version":"v1"},"tags":[{"name":"Tokenization"}],"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}$"},"CreateSubjectInput":{"type":"object","additionalProperties":false,"required":["profile","subject_name"],"properties":{"profile":{"$ref":"#/components/schemas/AadSafeText","maxLength":128},"subject_name":{"$ref":"#/components/schemas/AadSafeText","maxLength":128,"description":"Not whitespace-only; no controls, semicolon or equals. No trimming or Unicode normalization. Not stored or logged."}}},"AadSafeText":{"type":"string","minLength":1,"pattern":"^[^\\x00-\\x1F\\x7F-\\x9F;=]+$","description":"Text safe to embed in a key=value;... AAD string (no ';' or '=')."},"CreateSubjectOutput":{"type":"object","additionalProperties":false,"required":["kid","profile","subject"],"properties":{"kid":{"$ref":"#/components/schemas/Kid"},"profile":{"$ref":"#/components/schemas/AadSafeText"},"subject":{"$ref":"#/components/schemas/Subject"}}},"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."},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"$ref":"#/components/schemas/TextField"}}},"TextField":{"type":"string","minLength":1,"pattern":"^[^\\x00-\\x1F\\x7F-\\x9F]+$"}},"responses":{"RequestBodyTooLarge":{"description":"Request body exceeds the internal 2 MiB limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"UnsupportedMediaType":{"description":"Request body must use application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"TooManyRequests":{"description":"Cryptographic worker capacity exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Error":{"description":"Public error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/subject/{kid}":{"post":{"tags":["Tokenization"],"summary":"Create a stored subject seed","description":"Requires subject-create for this KID, an active key and a matching stored tokenization profile. The name is not stored. Idempotent retries return 200 with the same ID and never replace or repair the seed. Caller names are not normalized. The subject identifier is deterministic for the same KID, profile and exact name; the seed is random and is never returned. Retain the returned identifier for subject-bound token operations. No ref is required.\n","parameters":[{"$ref":"#/components/parameters/Kid"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSubjectInput"}}}},"responses":{"200":{"description":"Existing subject; same identifiers returned, seed unchanged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSubjectOutput"}}}},"201":{"description":"Created subject; seed material is never returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSubjectOutput"}}}},"400":{"description":"Invalid input, unknown profile or profile not configured as stored","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Missing subject-create grant, profile/KID mismatch or key not active","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Operational key not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"$ref":"#/components/responses/RequestBodyTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"429":{"$ref":"#/components/responses/TooManyRequests"},"default":{"$ref":"#/components/responses/Error"}}}}}}
```
## Atomically delete a stored subject seed and its tokens
> Requires subject-delete for this KID. Does not require a usable key or decrypt the seed. No request body, profile or JSON content type is required. Does not enforce key lifecycle or require the key to be loaded; authorization and valid path identifiers remain mandatory. All token rows for this KID and subject are purged in the same transaction; no additional token-delete grant is required. Subject-bound writes check the opened seed generation under a database lock and cannot insert after deletion or recreation. Operations that already read data may finish; backups can restore deleted material. No subject list/get endpoint is exposed.
```json
{"openapi":"3.1.0","info":{"title":"Vectis HTTP API","version":"v1"},"tags":[{"name":"Tokenization"}],"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."},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"$ref":"#/components/schemas/TextField"}}},"TextField":{"type":"string","minLength":1,"pattern":"^[^\\x00-\\x1F\\x7F-\\x9F]+$"}},"responses":{"Error":{"description":"Public error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/subject/{kid}/{subject}":{"delete":{"tags":["Tokenization"],"summary":"Atomically delete a stored subject seed and its tokens","description":"Requires subject-delete for this KID. Does not require a usable key or decrypt the seed. No request body, profile or JSON content type is required. Does not enforce key lifecycle or require the key to be loaded; authorization and valid path identifiers remain mandatory. All token rows for this KID and subject are purged in the same transaction; no additional token-delete grant is required. Subject-bound writes check the opened seed generation under a database lock and cannot insert after deletion or recreation. Operations that already read data may finish; backups can restore deleted material. No subject list/get endpoint is exposed.\n","parameters":[{"$ref":"#/components/parameters/Kid"},{"$ref":"#/components/parameters/Subject"}],"responses":{"204":{"description":"Subject seed and associated tokens deleted; empty response body"},"400":{"description":"Invalid KID or subject identifier","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Missing subject-delete grant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Subject not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"$ref":"#/components/responses/Error"}}}}}}
```
## Create a subject-bound token
> Requires token-encode, an active key, a matching stored profile and an existing subject seed. The insert checks the opened seed generation under a database lock. Concurrent deletion returns 404 subject not found; deletion followed by recreation returns 409 subject changed during token operation. Neither failure inserts or returns a token.
```json
{"openapi":"3.1.0","info":{"title":"Vectis HTTP API","version":"v1"},"tags":[{"name":"Tokenization"}],"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."},"TokenEncodeInput":{"type":"object","additionalProperties":false,"required":["ref","profile","plaintext"],"properties":{"ref":{"$ref":"#/components/schemas/ClientRef"},"profile":{"$ref":"#/components/schemas/TextField"},"plaintext":{"$ref":"#/components/schemas/TextField","maxLength":16384,"description":"Unicode character count must also fit the selected signed profile maximum."},"metadata":{"type":"object","description":"Optional JSON object. Its compact serialized JSON representation must be at most 128 characters. Object keys under the reserved $serde_json::private:: namespace are rejected at any nesting depth.","additionalProperties":true}}},"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]+$"},"SubjectTokenEncodeOutput":{"allOf":[{"$ref":"#/components/schemas/TokenEncodeOutput"},{"type":"object","required":["subject"]}]},"TokenEncodeOutput":{"type":"object","required":["ref","kid","profile","token"],"properties":{"subject":{"$ref":"#/components/schemas/Subject","description":"Required for stored profiles and absent for legacy none profiles."},"ref":{"$ref":"#/components/schemas/ClientRef"},"kid":{"$ref":"#/components/schemas/Kid"},"profile":{"$ref":"#/components/schemas/TextField"},"token":{"$ref":"#/components/schemas/TextField","description":"Visible token in the form _. The configured token_prefix is capped at 16 characters; the decoded random byte length equals the signed profile token_len."}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"$ref":"#/components/schemas/TextField"}}}},"responses":{"BadRequest":{"description":"Invalid JSON, field encoding, profile or request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"Required permission missing, profile/KID mismatch or key lifecycle disallows the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Operational key, subject or token not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"SubjectGenerationChanged":{"description":"Subject seed generation changed before token insertion; no tokens inserted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"RequestBodyTooLarge":{"description":"Request body exceeds the internal 2 MiB limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"UnsupportedMediaType":{"description":"Request body must use application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"TooManyRequests":{"description":"Cryptographic worker capacity exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Error":{"description":"Public error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/token/encode/{kid}/subject/{subject}":{"post":{"tags":["Tokenization"],"summary":"Create a subject-bound token","description":"Requires token-encode, an active key, a matching stored profile and an existing subject seed. The insert checks the opened seed generation under a database lock. Concurrent deletion returns 404 subject not found; deletion followed by recreation returns 409 subject changed during token operation. Neither failure inserts or returns a token.\n","parameters":[{"$ref":"#/components/parameters/Kid"},{"$ref":"#/components/parameters/Subject"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenEncodeInput"}}}},"responses":{"200":{"description":"Subject-bound token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubjectTokenEncodeOutput"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/SubjectGenerationChanged"},"413":{"$ref":"#/components/responses/RequestBodyTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"429":{"$ref":"#/components/responses/TooManyRequests"},"default":{"$ref":"#/components/responses/Error"}}}}}}
```
## Create an atomic batch of subject-bound tokens
> Requires token-encode, an active key and a matching stored profile; one existing subject applies to all items. Maximum 128 items. Before inserting, the transaction checks the opened seed generation under a database lock. Concurrent deletion returns 404 subject not found; recreation with a different seed returns 409 subject changed during token operation. Failures insert no tokens and return no partial items.
```json
{"openapi":"3.1.0","info":{"title":"Vectis HTTP API","version":"v1"},"tags":[{"name":"Tokenization"}],"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."},"TokenEncodeBatchInput":{"type":"object","additionalProperties":false,"required":["profile","items"],"properties":{"profile":{"$ref":"#/components/schemas/TextField"},"items":{"type":"array","minItems":1,"maxItems":128,"items":{"$ref":"#/components/schemas/TokenEncodeBatchItemInput"}}}},"TextField":{"type":"string","minLength":1,"pattern":"^[^\\x00-\\x1F\\x7F-\\x9F]+$"},"TokenEncodeBatchItemInput":{"type":"object","additionalProperties":false,"required":["ref","plaintext"],"properties":{"ref":{"$ref":"#/components/schemas/ClientRef"},"plaintext":{"$ref":"#/components/schemas/TextField","maxLength":16384,"description":"Unicode character count must also fit the selected signed profile maximum."},"metadata":{"type":"object","description":"Optional JSON object. Its compact serialized JSON representation must be at most 128 characters. Object keys under the reserved $serde_json::private:: namespace are rejected at any nesting depth.","additionalProperties":true}}},"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."},"SubjectTokenEncodeBatchOutput":{"allOf":[{"$ref":"#/components/schemas/TokenEncodeBatchOutput"},{"type":"object","required":["subject"]}]},"TokenEncodeBatchOutput":{"type":"object","required":["kid","profile","items"],"properties":{"subject":{"$ref":"#/components/schemas/Subject","description":"Required for stored profiles and absent for legacy none profiles."},"kid":{"$ref":"#/components/schemas/Kid"},"profile":{"$ref":"#/components/schemas/TextField"},"items":{"type":"array","items":{"$ref":"#/components/schemas/TokenEncodeBatchOutputItem"}}}},"TokenEncodeBatchOutputItem":{"type":"object","required":["ref","token"],"properties":{"ref":{"$ref":"#/components/schemas/ClientRef"},"token":{"$ref":"#/components/schemas/TextField","description":"Visible token in the form _. The configured token_prefix is capped at 16 characters; the decoded random byte length equals the signed profile token_len."}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"$ref":"#/components/schemas/TextField"}}}},"responses":{"BadRequest":{"description":"Invalid JSON, field encoding, profile or request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"Required permission missing, profile/KID mismatch or key lifecycle disallows the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Operational key, subject or token not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"SubjectGenerationChanged":{"description":"Subject seed generation changed before token insertion; no tokens inserted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"RequestBodyTooLarge":{"description":"Request body exceeds the internal 2 MiB limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"UnsupportedMediaType":{"description":"Request body must use application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"TooManyRequests":{"description":"Cryptographic worker capacity exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Error":{"description":"Public error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/token/encode/batch/{kid}/subject/{subject}":{"post":{"tags":["Tokenization"],"summary":"Create an atomic batch of subject-bound tokens","description":"Requires token-encode, an active key and a matching stored profile; one existing subject applies to all items. Maximum 128 items. Before inserting, the transaction checks the opened seed generation under a database lock. Concurrent deletion returns 404 subject not found; recreation with a different seed returns 409 subject changed during token operation. Failures insert no tokens and return no partial items.\n","parameters":[{"$ref":"#/components/parameters/Kid"},{"$ref":"#/components/parameters/Subject"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenEncodeBatchInput"}}}},"responses":{"200":{"description":"Complete subject-bound token batch","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubjectTokenEncodeBatchOutput"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/SubjectGenerationChanged"},"413":{"$ref":"#/components/responses/RequestBodyTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"429":{"$ref":"#/components/responses/TooManyRequests"},"default":{"$ref":"#/components/responses/Error"}}}}}}
```
## Create a reversible random token
> Creates a random visible token using a tokenization profile loaded from signed config in none subject mode. The database stores kid, hashid, encrypted data and a null subject association. The profile allows up to 16,384 Unicode plaintext characters; the encrypted storage envelope is limited to 131,072 Base64 characters. The key must be active. The client ref is echoed in the response.
```json
{"openapi":"3.1.0","info":{"title":"Vectis HTTP API","version":"v1"},"tags":[{"name":"Tokenization"}],"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}$"},"TokenEncodeInput":{"type":"object","additionalProperties":false,"required":["ref","profile","plaintext"],"properties":{"ref":{"$ref":"#/components/schemas/ClientRef"},"profile":{"$ref":"#/components/schemas/TextField"},"plaintext":{"$ref":"#/components/schemas/TextField","maxLength":16384,"description":"Unicode character count must also fit the selected signed profile maximum."},"metadata":{"type":"object","description":"Optional JSON object. Its compact serialized JSON representation must be at most 128 characters. Object keys under the reserved $serde_json::private:: namespace are rejected at any nesting depth.","additionalProperties":true}}},"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]+$"},"TokenEncodeOutput":{"type":"object","required":["ref","kid","profile","token"],"properties":{"subject":{"$ref":"#/components/schemas/Subject","description":"Required for stored profiles and absent for legacy none profiles."},"ref":{"$ref":"#/components/schemas/ClientRef"},"kid":{"$ref":"#/components/schemas/Kid"},"profile":{"$ref":"#/components/schemas/TextField"},"token":{"$ref":"#/components/schemas/TextField","description":"Visible token in the form _. The configured token_prefix is capped at 16 characters; the decoded random byte length equals the signed profile token_len."}}},"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."},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"$ref":"#/components/schemas/TextField"}}}},"responses":{"BadRequest":{"description":"Invalid JSON, field encoding, profile or request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"Required permission missing, profile/KID mismatch or key lifecycle disallows the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Operational key, subject or token not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"RequestBodyTooLarge":{"description":"Request body exceeds the internal 2 MiB limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"UnsupportedMediaType":{"description":"Request body must use application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"TooManyRequests":{"description":"Cryptographic worker capacity exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Error":{"description":"Public error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/token/encode/{kid}":{"post":{"tags":["Tokenization"],"summary":"Create a reversible random token","description":"Creates a random visible token using a tokenization profile loaded from signed config in none subject mode. The database stores kid, hashid, encrypted data and a null subject association. The profile allows up to 16,384 Unicode plaintext characters; the encrypted storage envelope is limited to 131,072 Base64 characters. The key must be active. The client ref is echoed in the response.\n","parameters":[{"$ref":"#/components/parameters/Kid"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenEncodeInput"}}}},"responses":{"200":{"description":"Created token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenEncodeOutput"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"413":{"$ref":"#/components/responses/RequestBodyTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"429":{"$ref":"#/components/responses/TooManyRequests"},"default":{"$ref":"#/components/responses/Error"}}}}}}
```
## Create reversible random tokens as an all-or-nothing batch
> Creates random visible tokens using one tokenization profile loaded from signed config in none subject mode. The subject column remains null. Each item must include a unique client ref, which is echoed in the corresponding response item. The key must be active. All token rows are inserted in one storage transaction; any item failure returns one error and no partial items.
```json
{"openapi":"3.1.0","info":{"title":"Vectis HTTP API","version":"v1"},"tags":[{"name":"Tokenization"}],"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}$"},"TokenEncodeBatchInput":{"type":"object","additionalProperties":false,"required":["profile","items"],"properties":{"profile":{"$ref":"#/components/schemas/TextField"},"items":{"type":"array","minItems":1,"maxItems":128,"items":{"$ref":"#/components/schemas/TokenEncodeBatchItemInput"}}}},"TextField":{"type":"string","minLength":1,"pattern":"^[^\\x00-\\x1F\\x7F-\\x9F]+$"},"TokenEncodeBatchItemInput":{"type":"object","additionalProperties":false,"required":["ref","plaintext"],"properties":{"ref":{"$ref":"#/components/schemas/ClientRef"},"plaintext":{"$ref":"#/components/schemas/TextField","maxLength":16384,"description":"Unicode character count must also fit the selected signed profile maximum."},"metadata":{"type":"object","description":"Optional JSON object. Its compact serialized JSON representation must be at most 128 characters. Object keys under the reserved $serde_json::private:: namespace are rejected at any nesting depth.","additionalProperties":true}}},"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."},"TokenEncodeBatchOutput":{"type":"object","required":["kid","profile","items"],"properties":{"subject":{"$ref":"#/components/schemas/Subject","description":"Required for stored profiles and absent for legacy none profiles."},"kid":{"$ref":"#/components/schemas/Kid"},"profile":{"$ref":"#/components/schemas/TextField"},"items":{"type":"array","items":{"$ref":"#/components/schemas/TokenEncodeBatchOutputItem"}}}},"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."},"TokenEncodeBatchOutputItem":{"type":"object","required":["ref","token"],"properties":{"ref":{"$ref":"#/components/schemas/ClientRef"},"token":{"$ref":"#/components/schemas/TextField","description":"Visible token in the form _. The configured token_prefix is capped at 16 characters; the decoded random byte length equals the signed profile token_len."}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"$ref":"#/components/schemas/TextField"}}}},"responses":{"BadRequest":{"description":"Invalid JSON, field encoding, profile or request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"Required permission missing, profile/KID mismatch or key lifecycle disallows the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Operational key, subject or token not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"RequestBodyTooLarge":{"description":"Request body exceeds the internal 2 MiB limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"UnsupportedMediaType":{"description":"Request body must use application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"TooManyRequests":{"description":"Cryptographic worker capacity exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Error":{"description":"Public error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/token/encode/batch/{kid}":{"post":{"tags":["Tokenization"],"summary":"Create reversible random tokens as an all-or-nothing batch","description":"Creates random visible tokens using one tokenization profile loaded from signed config in none subject mode. The subject column remains null. Each item must include a unique client ref, which is echoed in the corresponding response item. The key must be active. All token rows are inserted in one storage transaction; any item failure returns one error and no partial items.\n","parameters":[{"$ref":"#/components/parameters/Kid"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenEncodeBatchInput"}}}},"responses":{"200":{"description":"Created tokens","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenEncodeBatchOutput"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"413":{"$ref":"#/components/responses/RequestBodyTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"429":{"$ref":"#/components/responses/TooManyRequests"},"default":{"$ref":"#/components/responses/Error"}}}}}}
```
## Resolve a reversible random token
> Resolves a token by HMAC-derived hashid and decrypts the stored payload. Decode 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":"Tokenization"}],"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":{"TokenDecodeInput":{"type":"object","additionalProperties":false,"required":["ref","kid","profile","token"],"properties":{"subject":{"$ref":"#/components/schemas/Subject","description":"Required for stored profiles and absent for legacy none profiles."},"ref":{"$ref":"#/components/schemas/ClientRef"},"kid":{"$ref":"#/components/schemas/Kid"},"profile":{"$ref":"#/components/schemas/TextField"},"token":{"$ref":"#/components/schemas/TextField","description":"Visible token in the form _. Decode validates the configured prefix (capped at 16 characters) and decoded byte length before lookup."}}},"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."},"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}$"},"TextField":{"type":"string","minLength":1,"pattern":"^[^\\x00-\\x1F\\x7F-\\x9F]+$"},"TokenDecodeOutput":{"type":"object","required":["ref","plaintext"],"properties":{"ref":{"$ref":"#/components/schemas/ClientRef"},"plaintext":{"$ref":"#/components/schemas/TextField"},"metadata":{"type":"object","additionalProperties":true}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"$ref":"#/components/schemas/TextField"}}}},"responses":{"BadRequest":{"description":"Invalid JSON, field encoding, profile or request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"Required permission missing, profile/KID mismatch or key lifecycle disallows the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Operational key, subject or token not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"RequestBodyTooLarge":{"description":"Request body exceeds the internal 2 MiB limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"UnsupportedMediaType":{"description":"Request body must use application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"TooManyRequests":{"description":"Cryptographic worker capacity exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Error":{"description":"Public error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/token/decode":{"post":{"tags":["Tokenization"],"summary":"Resolve a reversible random token","description":"Resolves a token by HMAC-derived hashid and decrypts the stored payload. Decode permits active and retired keys. The client ref is echoed in the response.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenDecodeInput"}}}},"responses":{"200":{"description":"Token plaintext and optional metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenDecodeOutput"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"413":{"$ref":"#/components/responses/RequestBodyTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"429":{"$ref":"#/components/responses/TooManyRequests"},"default":{"$ref":"#/components/responses/Error"}}}}}}
```
## Delete a stored token without decrypting its payload
> Requires the independent token-delete grant for the request KID. Deletion is permitted in any key lifecycle state, so token rows can be purged even after the key is disabled or destroyed. Deletes reusable or one-time tokens after computing their HMAC hashid, without reading the envelope. Success is returned only after commit. Missing, deleted, or consumed tokens return 404 token not found. An already-running reusable decode may complete; older backups can restore deleted tokens.
```json
{"openapi":"3.1.0","info":{"title":"Vectis HTTP API","version":"v1"},"tags":[{"name":"Tokenization"}],"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":{"TokenDeleteInput":{"type":"object","additionalProperties":false,"required":["ref","kid","profile","token"],"properties":{"subject":{"$ref":"#/components/schemas/Subject","description":"Required for stored profiles and absent for legacy none profiles."},"ref":{"$ref":"#/components/schemas/ClientRef"},"kid":{"$ref":"#/components/schemas/Kid"},"profile":{"$ref":"#/components/schemas/AadSafeText"},"token":{"$ref":"#/components/schemas/TextField"}}},"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."},"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}$"},"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]+$"},"TokenDeleteOutput":{"type":"object","additionalProperties":false,"required":["ref","deleted"],"properties":{"ref":{"$ref":"#/components/schemas/ClientRef"},"deleted":{"type":"boolean","const":true}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"$ref":"#/components/schemas/TextField"}}}},"responses":{"BadRequest":{"description":"Invalid JSON, field encoding, profile or request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"Required permission missing, profile/KID mismatch or key lifecycle disallows the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Operational key, subject or token not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"RequestBodyTooLarge":{"description":"Request body exceeds the internal 2 MiB limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"UnsupportedMediaType":{"description":"Request body must use application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"TooManyRequests":{"description":"Cryptographic worker capacity exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Error":{"description":"Public error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/token/delete":{"post":{"tags":["Tokenization"],"summary":"Delete a stored token without decrypting its payload","description":"Requires the independent token-delete grant for the request KID. Deletion is permitted in any key lifecycle state, so token rows can be purged even after the key is disabled or destroyed. Deletes reusable or one-time tokens after computing their HMAC hashid, without reading the envelope. Success is returned only after commit. Missing, deleted, or consumed tokens return 404 token not found. An already-running reusable decode may complete; older backups can restore deleted tokens.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenDeleteInput"}}}},"responses":{"200":{"description":"The token row was deleted and committed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenDeleteOutput"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"413":{"$ref":"#/components/responses/RequestBodyTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"429":{"$ref":"#/components/responses/TooManyRequests"},"default":{"$ref":"#/components/responses/Error"}}}}}}
```
## Resolve reversible random tokens as an all-or-nothing batch
> Resolves tokens by HMAC-derived hashid and decrypts the stored payloads. Each item must include a unique client ref, which is echoed in the corresponding response item. Decode permits active and retired keys. If any item fails, the response is one error and no partial items are returned. Incremental storage reads have a fixed 5 MiB envelope budget, counting each requested occurrence, including repeated reusable tokens. Exceeding it returns 413 before decrypt or one-time consumption. Accepted batches return complete results without an additional response-size cap.
```json
{"openapi":"3.1.0","info":{"title":"Vectis HTTP API","version":"v1"},"tags":[{"name":"Tokenization"}],"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":{"TokenDecodeBatchInput":{"type":"object","additionalProperties":false,"required":["kid","profile","items"],"properties":{"subject":{"$ref":"#/components/schemas/Subject","description":"Required for stored profiles and absent for legacy none profiles."},"kid":{"$ref":"#/components/schemas/Kid"},"profile":{"$ref":"#/components/schemas/TextField"},"items":{"type":"array","minItems":1,"maxItems":128,"items":{"$ref":"#/components/schemas/TokenDecodeBatchItemInput"}}}},"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."},"Kid":{"type":"string","pattern":"^[0-9a-fA-F]{64}$"},"TextField":{"type":"string","minLength":1,"pattern":"^[^\\x00-\\x1F\\x7F-\\x9F]+$"},"TokenDecodeBatchItemInput":{"type":"object","additionalProperties":false,"required":["ref","token"],"properties":{"ref":{"$ref":"#/components/schemas/ClientRef"},"token":{"$ref":"#/components/schemas/TextField","description":"Visible token in the form _. Decode validates the configured prefix (capped at 16 characters) and decoded byte length before lookup."}}},"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."},"TokenDecodeBatchOutput":{"type":"object","required":["kid","profile","items"],"properties":{"kid":{"$ref":"#/components/schemas/Kid"},"profile":{"$ref":"#/components/schemas/TextField"},"items":{"type":"array","items":{"$ref":"#/components/schemas/TokenDecodeBatchOutputItem"}}}},"TokenDecodeBatchOutputItem":{"type":"object","required":["ref","plaintext"],"properties":{"ref":{"$ref":"#/components/schemas/ClientRef"},"plaintext":{"$ref":"#/components/schemas/TextField"},"metadata":{"type":"object","additionalProperties":true}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"$ref":"#/components/schemas/TextField"}}}},"responses":{"BadRequest":{"description":"Invalid JSON, field encoding, profile or request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"Required permission missing, profile/KID mismatch or key lifecycle disallows the operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Operational key, subject or token not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"UnsupportedMediaType":{"description":"Request body must use application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"TooManyRequests":{"description":"Cryptographic worker capacity exhausted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Error":{"description":"Public error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/token/decode/batch":{"post":{"tags":["Tokenization"],"summary":"Resolve reversible random tokens as an all-or-nothing batch","description":"Resolves tokens by HMAC-derived hashid and decrypts the stored payloads. Each item must include a unique client ref, which is echoed in the corresponding response item. Decode permits active and retired keys. If any item fails, the response is one error and no partial items are returned. Incremental storage reads have a fixed 5 MiB envelope budget, counting each requested occurrence, including repeated reusable tokens. Exceeding it returns 413 before decrypt or one-time consumption. Accepted batches return complete results without an additional response-size cap.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenDecodeBatchInput"}}}},"responses":{"200":{"description":"Token plaintexts and optional metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenDecodeBatchOutput"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"413":{"description":"Request body exceeds 2 MiB or stored token envelopes exceed the 5 MiB batch budget","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"429":{"$ref":"#/components/responses/TooManyRequests"},"default":{"$ref":"#/components/responses/Error"}}}}}}
```