> 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/secret-sharing.md).

# Secret Sharing

## Split a UTF-8 secret into authenticated Shamir shares

> Creates a stateless vectis-sss-v1 sharing set. The configured threshold and total share count are returned in authenticated share envelopes. Requires an active key.

```json
{"openapi":"3.1.0","info":{"title":"Vectis HTTP API","version":"v1"},"tags":[{"name":"Secret Sharing"}],"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}$"},"ShareSplitInput":{"type":"object","additionalProperties":false,"required":["profile","plaintext"],"properties":{"profile":{"$ref":"#/components/schemas/AadSafeText"},"plaintext":{"$ref":"#/components/schemas/TextField"}}},"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]+$"},"ShareSplitOutput":{"type":"object","required":["kid","profile","threshold","set_id","shares"],"properties":{"kid":{"$ref":"#/components/schemas/Kid"},"profile":{"$ref":"#/components/schemas/AadSafeText"},"threshold":{"type":"integer","minimum":2},"set_id":{"$ref":"#/components/schemas/Base64UrlNoPad"},"shares":{"type":"array","minItems":2,"maxItems":32,"items":{"type":"string","pattern":"^vectis-sss-v1\\.[A-Za-z0-9_-]+$"}}}},"Base64UrlNoPad":{"type":"string","pattern":"^[A-Za-z0-9_-]+$"},"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":{"/shares/split/{kid}":{"post":{"tags":["Secret Sharing"],"summary":"Split a UTF-8 secret into authenticated Shamir shares","description":"Creates a stateless vectis-sss-v1 sharing set. The configured threshold and total share count are returned in authenticated share envelopes. Requires an active key.","parameters":[{"$ref":"#/components/parameters/Kid"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShareSplitInput"}}}},"responses":{"200":{"description":"Authenticated Shamir shares","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShareSplitOutput"}}}},"413":{"$ref":"#/components/responses/RequestBodyTooLarge"},"default":{"$ref":"#/components/responses/Error"}}}}}}
```

## Combine authenticated Shamir shares

> Validates share tags and profile/KID/set consistency before reconstructing the UTF-8 secret. Requires an active or retired key.

```json
{"openapi":"3.1.0","info":{"title":"Vectis HTTP API","version":"v1"},"tags":[{"name":"Secret Sharing"}],"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":{"ShareCombineInput":{"type":"object","additionalProperties":false,"required":["kid","profile","shares"],"properties":{"kid":{"$ref":"#/components/schemas/Kid"},"profile":{"$ref":"#/components/schemas/AadSafeText"},"shares":{"type":"array","minItems":2,"maxItems":32,"items":{"type":"string","pattern":"^vectis-sss-v1\\.[A-Za-z0-9_-]+$"}}}},"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 '=')."},"ShareCombineOutput":{"type":"object","required":["kid","profile","set_id","plaintext"],"properties":{"kid":{"$ref":"#/components/schemas/Kid"},"profile":{"$ref":"#/components/schemas/AadSafeText"},"set_id":{"$ref":"#/components/schemas/Base64UrlNoPad"},"plaintext":{"$ref":"#/components/schemas/TextField"}}},"Base64UrlNoPad":{"type":"string","pattern":"^[A-Za-z0-9_-]+$"},"TextField":{"type":"string","minLength":1,"pattern":"^[^\\x00-\\x1F\\x7F-\\x9F]+$"},"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":{"/shares/combine":{"post":{"tags":["Secret Sharing"],"summary":"Combine authenticated Shamir shares","description":"Validates share tags and profile/KID/set consistency before reconstructing the UTF-8 secret. Requires an active or retired key.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShareCombineInput"}}}},"responses":{"200":{"description":"Reconstructed secret","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShareCombineOutput"}}}},"413":{"$ref":"#/components/responses/RequestBodyTooLarge"},"default":{"$ref":"#/components/responses/Error"}}}}}}
```