> 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/deterministic-tokenization.md).

# Deterministic Tokenization

## Encode deterministic authenticated token

> Requires token-deterministic-encode for the KID. Active keys only. Signed subject\_mode must be none on this route. No per-token storage.

```json
{"openapi":"3.1.0","info":{"title":"Vectis HTTP API","version":"v1"},"tags":[{"name":"Deterministic 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":{"DeterministicTokenEncodeInput":{"type":"object","additionalProperties":false,"required":["ref","profile","plaintext"],"properties":{"ref":{"$ref":"#/components/schemas/ClientRef"},"profile":{"type":"string","minLength":1,"maxLength":128},"plaintext":{"type":"string","minLength":1,"maxLength":16384,"description":"Unicode scalar count, also bounded by the signed profile."}}},"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."},"DeterministicTokenEncodeOutput":{"type":"object","additionalProperties":false,"required":["ref","kid","profile","token"],"properties":{"ref":{"$ref":"#/components/schemas/ClientRef"},"kid":{"$ref":"#/components/schemas/Kid"},"profile":{"type":"string","minLength":1,"maxLength":128},"token":{"type":"string","maxLength":131072,"pattern":"^[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$","description":"Canonical context and complete AES-256-SIV output, Base64URL without padding."},"subject":{"$ref":"#/components/schemas/Subject"}}},"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":{"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"}}}}},"parameters":{"Kid":{"name":"kid","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Kid"}}}},"paths":{"/token/deterministic/encode/{kid}":{"post":{"tags":["Deterministic Tokenization"],"summary":"Encode deterministic authenticated token","description":"Requires token-deterministic-encode for the KID. Active keys only. Signed subject_mode must be none on this route. No per-token storage.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeterministicTokenEncodeInput"}}}},"responses":{"200":{"description":"Complete authenticated result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeterministicTokenEncodeOutput"}}}},"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"}},"parameters":[{"$ref":"#/components/parameters/Kid"}]}}}}
```

## Encode deterministic authenticated token

> Requires token-deterministic-encode for the KID. Active keys only. Signed subject\_mode must be stored on this route; the subject seed must exist. No fallback or per-token storage.

```json
{"openapi":"3.1.0","info":{"title":"Vectis HTTP API","version":"v1"},"tags":[{"name":"Deterministic 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":{"DeterministicTokenEncodeInput":{"type":"object","additionalProperties":false,"required":["ref","profile","plaintext"],"properties":{"ref":{"$ref":"#/components/schemas/ClientRef"},"profile":{"type":"string","minLength":1,"maxLength":128},"plaintext":{"type":"string","minLength":1,"maxLength":16384,"description":"Unicode scalar count, also bounded by the signed profile."}}},"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."},"DeterministicTokenEncodeOutput":{"type":"object","additionalProperties":false,"required":["ref","kid","profile","token"],"properties":{"ref":{"$ref":"#/components/schemas/ClientRef"},"kid":{"$ref":"#/components/schemas/Kid"},"profile":{"type":"string","minLength":1,"maxLength":128},"token":{"type":"string","maxLength":131072,"pattern":"^[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$","description":"Canonical context and complete AES-256-SIV output, Base64URL without padding."},"subject":{"$ref":"#/components/schemas/Subject"}}},"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":{"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"}}}}},"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"}}}},"paths":{"/token/deterministic/encode/{kid}/subject/{subject}":{"post":{"tags":["Deterministic Tokenization"],"summary":"Encode deterministic authenticated token","description":"Requires token-deterministic-encode for the KID. Active keys only. Signed subject_mode must be stored on this route; the subject seed must exist. No fallback or per-token storage.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeterministicTokenEncodeInput"}}}},"responses":{"200":{"description":"Complete authenticated result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeterministicTokenEncodeOutput"}}}},"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"}},"parameters":[{"$ref":"#/components/parameters/Kid"},{"$ref":"#/components/parameters/Subject"}]}}}}
```

## Encode deterministic authenticated tokens in order

> Requires token-deterministic-encode for the KID. Active keys only. Signed subject\_mode must be none on this route. No per-token storage. At most 128 unique refs; no partial results.

```json
{"openapi":"3.1.0","info":{"title":"Vectis HTTP API","version":"v1"},"tags":[{"name":"Deterministic 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":{"DeterministicTokenEncodeBatchInput":{"type":"object","additionalProperties":false,"required":["profile","items"],"properties":{"profile":{"type":"string","minLength":1,"maxLength":128},"items":{"type":"array","minItems":1,"maxItems":128,"items":{"$ref":"#/components/schemas/DeterministicTokenEncodeBatchItemInput"}}}},"DeterministicTokenEncodeBatchItemInput":{"type":"object","additionalProperties":false,"required":["ref","plaintext"],"properties":{"ref":{"$ref":"#/components/schemas/ClientRef"},"plaintext":{"type":"string","minLength":1,"maxLength":16384,"description":"Unicode scalar count, also bounded by the signed profile."}}},"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."},"DeterministicTokenEncodeBatchOutput":{"type":"object","additionalProperties":false,"required":["kid","profile","items"],"properties":{"kid":{"$ref":"#/components/schemas/Kid"},"profile":{"type":"string","minLength":1,"maxLength":128},"subject":{"$ref":"#/components/schemas/Subject"},"items":{"type":"array","minItems":1,"maxItems":128,"items":{"$ref":"#/components/schemas/DeterministicTokenEncodeBatchItemOutput"}}}},"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."},"DeterministicTokenEncodeBatchItemOutput":{"type":"object","additionalProperties":false,"required":["ref","token"],"properties":{"ref":{"$ref":"#/components/schemas/ClientRef"},"token":{"type":"string","maxLength":131072,"pattern":"^[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$","description":"Canonical context and complete AES-256-SIV output, Base64URL without padding."}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"$ref":"#/components/schemas/TextField"}}},"TextField":{"type":"string","minLength":1,"pattern":"^[^\\x00-\\x1F\\x7F-\\x9F]+$"}},"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"}}}}},"parameters":{"Kid":{"name":"kid","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Kid"}}}},"paths":{"/token/deterministic/encode/batch/{kid}":{"post":{"tags":["Deterministic Tokenization"],"summary":"Encode deterministic authenticated tokens in order","description":"Requires token-deterministic-encode for the KID. Active keys only. Signed subject_mode must be none on this route. No per-token storage. At most 128 unique refs; no partial results.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeterministicTokenEncodeBatchInput"}}}},"responses":{"200":{"description":"Complete authenticated result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeterministicTokenEncodeBatchOutput"}}}},"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"}},"parameters":[{"$ref":"#/components/parameters/Kid"}]}}}}
```

## Encode deterministic authenticated tokens in order

> Requires token-deterministic-encode for the KID. Active keys only. Signed subject\_mode must be stored; the subject seed must exist. No fallback or per-token storage. At most 128 unique refs; no partial results.

```json
{"openapi":"3.1.0","info":{"title":"Vectis HTTP API","version":"v1"},"tags":[{"name":"Deterministic 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":{"DeterministicTokenEncodeBatchInput":{"type":"object","additionalProperties":false,"required":["profile","items"],"properties":{"profile":{"type":"string","minLength":1,"maxLength":128},"items":{"type":"array","minItems":1,"maxItems":128,"items":{"$ref":"#/components/schemas/DeterministicTokenEncodeBatchItemInput"}}}},"DeterministicTokenEncodeBatchItemInput":{"type":"object","additionalProperties":false,"required":["ref","plaintext"],"properties":{"ref":{"$ref":"#/components/schemas/ClientRef"},"plaintext":{"type":"string","minLength":1,"maxLength":16384,"description":"Unicode scalar count, also bounded by the signed profile."}}},"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."},"DeterministicTokenEncodeBatchOutput":{"type":"object","additionalProperties":false,"required":["kid","profile","items"],"properties":{"kid":{"$ref":"#/components/schemas/Kid"},"profile":{"type":"string","minLength":1,"maxLength":128},"subject":{"$ref":"#/components/schemas/Subject"},"items":{"type":"array","minItems":1,"maxItems":128,"items":{"$ref":"#/components/schemas/DeterministicTokenEncodeBatchItemOutput"}}}},"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."},"DeterministicTokenEncodeBatchItemOutput":{"type":"object","additionalProperties":false,"required":["ref","token"],"properties":{"ref":{"$ref":"#/components/schemas/ClientRef"},"token":{"type":"string","maxLength":131072,"pattern":"^[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$","description":"Canonical context and complete AES-256-SIV output, Base64URL without padding."}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"$ref":"#/components/schemas/TextField"}}},"TextField":{"type":"string","minLength":1,"pattern":"^[^\\x00-\\x1F\\x7F-\\x9F]+$"}},"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"}}}}},"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"}}}},"paths":{"/token/deterministic/encode/batch/{kid}/subject/{subject}":{"post":{"tags":["Deterministic Tokenization"],"summary":"Encode deterministic authenticated tokens in order","description":"Requires token-deterministic-encode for the KID. Active keys only. Signed subject_mode must be stored; the subject seed must exist. No fallback or per-token storage. At most 128 unique refs; no partial results.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeterministicTokenEncodeBatchInput"}}}},"responses":{"200":{"description":"Complete authenticated result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeterministicTokenEncodeBatchOutput"}}}},"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"}},"parameters":[{"$ref":"#/components/parameters/Kid"},{"$ref":"#/components/parameters/Subject"}]}}}}
```

## Decode deterministic authenticated token

> Requires token-deterministic-decode for the KID. Active or retired keys only. Signed subject\_mode requires subject for stored and prohibits it for none; violations return 400 before seed lookup. Missing required seed returns 404. No fallback or per-token storage.

```json
{"openapi":"3.1.0","info":{"title":"Vectis HTTP API","version":"v1"},"tags":[{"name":"Deterministic 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":{"DeterministicTokenDecodeInput":{"type":"object","additionalProperties":false,"description":"Subject is required for stored profiles and prohibited for none profiles. Null is invalid.","required":["ref","kid","profile","token"],"properties":{"ref":{"$ref":"#/components/schemas/ClientRef"},"kid":{"$ref":"#/components/schemas/Kid"},"profile":{"type":"string","minLength":1,"maxLength":128},"token":{"type":"string","maxLength":131072,"pattern":"^[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$","description":"Canonical context and complete AES-256-SIV output, Base64URL without padding."},"subject":{"$ref":"#/components/schemas/Subject"}}},"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."},"DeterministicTokenDecodeOutput":{"type":"object","additionalProperties":false,"required":["ref","kid","profile","plaintext"],"properties":{"ref":{"$ref":"#/components/schemas/ClientRef"},"kid":{"$ref":"#/components/schemas/Kid"},"profile":{"type":"string","minLength":1,"maxLength":128},"plaintext":{"type":"string","minLength":1,"maxLength":16384,"description":"Unicode scalar count, also bounded by the signed profile."},"subject":{"$ref":"#/components/schemas/Subject"}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"$ref":"#/components/schemas/TextField"}}},"TextField":{"type":"string","minLength":1,"pattern":"^[^\\x00-\\x1F\\x7F-\\x9F]+$"}},"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/deterministic/decode":{"post":{"tags":["Deterministic Tokenization"],"summary":"Decode deterministic authenticated token","description":"Requires token-deterministic-decode for the KID. Active or retired keys only. Signed subject_mode requires subject for stored and prohibits it for none; violations return 400 before seed lookup. Missing required seed returns 404. No fallback or per-token storage.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeterministicTokenDecodeInput"}}}},"responses":{"200":{"description":"Complete authenticated result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeterministicTokenDecodeOutput"}}}},"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"}}}}}}
```

## Decode deterministic authenticated tokens in order

> Requires token-deterministic-decode for the KID. Active or retired keys only. Signed subject\_mode requires the common subject for stored and prohibits it for none. Missing required seed returns 404. No fallback or per-token storage. At most 128 unique refs; no partial results.

```json
{"openapi":"3.1.0","info":{"title":"Vectis HTTP API","version":"v1"},"tags":[{"name":"Deterministic 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":{"DeterministicTokenDecodeBatchInput":{"type":"object","additionalProperties":false,"description":"One common subject for all items, required for stored profiles and prohibited for none profiles. Null is invalid.","required":["kid","profile","items"],"properties":{"kid":{"$ref":"#/components/schemas/Kid"},"profile":{"type":"string","minLength":1,"maxLength":128},"subject":{"$ref":"#/components/schemas/Subject"},"items":{"type":"array","minItems":1,"maxItems":128,"items":{"$ref":"#/components/schemas/DeterministicTokenDecodeBatchItemInput"}}}},"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."},"DeterministicTokenDecodeBatchItemInput":{"type":"object","additionalProperties":false,"required":["ref","token"],"properties":{"ref":{"$ref":"#/components/schemas/ClientRef"},"token":{"type":"string","maxLength":131072,"pattern":"^[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$","description":"Canonical context and complete AES-256-SIV output, Base64URL without padding."}}},"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."},"DeterministicTokenDecodeBatchOutput":{"type":"object","additionalProperties":false,"required":["kid","profile","items"],"properties":{"kid":{"$ref":"#/components/schemas/Kid"},"profile":{"type":"string","minLength":1,"maxLength":128},"subject":{"$ref":"#/components/schemas/Subject"},"items":{"type":"array","minItems":1,"maxItems":128,"items":{"$ref":"#/components/schemas/DeterministicTokenDecodeBatchItemOutput"}}}},"DeterministicTokenDecodeBatchItemOutput":{"type":"object","additionalProperties":false,"required":["ref","plaintext"],"properties":{"ref":{"$ref":"#/components/schemas/ClientRef"},"plaintext":{"type":"string","minLength":1,"maxLength":16384,"description":"Unicode scalar count, also bounded by the signed profile."}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"$ref":"#/components/schemas/TextField"}}},"TextField":{"type":"string","minLength":1,"pattern":"^[^\\x00-\\x1F\\x7F-\\x9F]+$"}},"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/deterministic/decode/batch":{"post":{"tags":["Deterministic Tokenization"],"summary":"Decode deterministic authenticated tokens in order","description":"Requires token-deterministic-decode for the KID. Active or retired keys only. Signed subject_mode requires the common subject for stored and prohibits it for none. Missing required seed returns 404. No fallback or per-token storage. At most 128 unique refs; no partial results.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeterministicTokenDecodeBatchInput"}}}},"responses":{"200":{"description":"Complete authenticated result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeterministicTokenDecodeBatchOutput"}}}},"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"}}}}}}
```