> For the complete documentation index, see [llms.txt](https://docs.zetrix.com/en/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zetrix.com/en/developer-resources/blockchain-as-a-services-baas/zetrix-service/hsm.md).

# HSM

Hardware Security Module — Thales Luna Cloud (DPoD)

## Create HSM key pair

> Generates an Ed25519 key pair on the HSM partition. Returns the Zetrix address and raw public key hex. The returned address is used as the identifier for subsequent sign requests.

```json
{"openapi":"3.1.0","info":{"title":"Zetrix Microservice API","version":"1.0.0"},"tags":[{"name":"HSM","description":"Hardware Security Module — Thales Luna Cloud (DPoD)"}],"servers":[{"url":"https://api-sandbox.zetrix.com","description":"Sandbox Environment – Use this for development and testing."}],"security":[{"Authorization":[]}],"components":{"securitySchemes":{"Authorization":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer access token. Include in all requests as: `Authorization: Bearer <your_access_token>`"}},"parameters":{"X-API-Key":{"name":"X-API-Key","in":"header","required":true,"description":"API key for authentication. Include in all requests.","schema":{"type":"string"}}},"schemas":{"HsmCreateAccountReqDto":{"type":"object","description":"Request to create an HSM-backed Ed25519 key pair","properties":{"label":{"type":"string","description":"Optional caller-supplied label suffix. Final key label = ZETRIX_<label> if provided, else ZETRIX_<uuid>."},"purpose":{"type":"string","description":"Optional purpose description for this key"},"password":{"type":"string","description":"User password used to encrypt the HSM key label in DB storage","minLength":8,"maxLength":128}},"required":["password"]},"ResponseWrapperHsmCreateAccountRespDto":{"type":"object","properties":{"object":{"$ref":"#/components/schemas/HsmCreateAccountRespDto"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/ResponseMessage"}},"success":{"type":"boolean"},"timestamp":{"type":"string","format":"date-time"},"traceId":{"type":"string"}}},"HsmCreateAccountRespDto":{"type":"object","description":"Response for HSM key pair creation","properties":{"publicKeyHex":{"type":"string","description":"Raw Ed25519 public key as hex string (64 hex chars = 32 bytes)"},"zetrixAddress":{"type":"string","description":"Zetrix blockchain address derived from the public key (e.g. ZTX3...). Use this as the identifier in subsequent sign requests."}}},"ResponseMessage":{"type":"object","description":"A response message indicating informational, warning, or error details.","properties":{"type":{"type":"string","description":"Severity: `INFO`, `WARNING`, or `ERROR`.","enum":["INFO","ERROR","WARNING"]},"errorCode":{"type":"integer","format":"int32","description":"Numeric error code (0 = no error)."},"message":{"type":"string","description":"Human-readable description."}}}}},"paths":{"/ztx/hsm/create-account":{"post":{"tags":["HSM"],"summary":"Create HSM key pair","operationId":"createAccount","description":"Generates an Ed25519 key pair on the HSM partition. Returns the Zetrix address and raw public key hex. The returned address is used as the identifier for subsequent sign requests.","parameters":[{"$ref":"#/components/parameters/X-API-Key"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HsmCreateAccountReqDto"}}}},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResponseWrapperHsmCreateAccountRespDto"}}}}}}}}}
```

## Sign blob with HSM

> Signs a hex-encoded transaction blob using the HSM-stored Ed25519 private key identified by the Zetrix address. The returned SignerEntity can be used directly in /tx/submit or /contract/submit.

```json
{"openapi":"3.1.0","info":{"title":"Zetrix Microservice API","version":"1.0.0"},"tags":[{"name":"HSM","description":"Hardware Security Module — Thales Luna Cloud (DPoD)"}],"servers":[{"url":"https://public-api-sandbox.zetrix.com"}],"security":[],"paths":{"/api/hsm/sign-blob":{"post":{"tags":["HSM"],"summary":"Sign blob with HSM","operationId":"signBlobHsm","description":"Signs a hex-encoded transaction blob using the HSM-stored Ed25519 private key identified by the Zetrix address. The returned SignerEntity can be used directly in /tx/submit or /contract/submit.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HsmBlobDataReqDto"}}}},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResponseWrapperListSignerEntity"}}}}}}}},"components":{"schemas":{"HsmBlobDataReqDto":{"type":"object","description":"Request to sign a transaction blob using the HSM","properties":{"blob":{"type":"string","description":"Hex-encoded transaction blob to sign (obtained from /tx/generate-blob or /contract/generate-blob)"},"password":{"type":"string","description":"User password used to decrypt the stored HSM key label","minLength":8,"maxLength":128},"address":{"type":"string","description":"Zetrix address returned by /hsm/create-account"}},"required":["blob","password","address"]},"ResponseWrapperListSignerEntity":{"type":"object","properties":{"object":{"type":"array","items":{"$ref":"#/components/schemas/SignerEntity"}},"messages":{"type":"array","items":{"$ref":"#/components/schemas/ResponseMessage"}},"success":{"type":"boolean"},"timestamp":{"type":"string","format":"date-time"},"traceId":{"type":"string"}}},"SignerEntity":{"type":"object","description":"A signer object containing a signature and public key pair. Used in transaction/contract submission requests.","properties":{"signBlob":{"type":"string","description":"Hex-encoded Ed25519 signature of the transaction blob."},"publicKey":{"type":"string","description":"Hex-encoded Ed25519 public key of the signer. Must be exactly 76 characters.","minLength":76,"maxLength":76}}},"ResponseMessage":{"type":"object","description":"A response message indicating informational, warning, or error details.","properties":{"type":{"type":"string","description":"Severity: `INFO`, `WARNING`, or `ERROR`.","enum":["INFO","ERROR","WARNING"]},"errorCode":{"type":"integer","format":"int32","description":"Numeric error code (0 = no error)."},"message":{"type":"string","description":"Human-readable description."}}}}}}
```

## Sign message with HSM

> Signs a UTF-8 message using the HSM-stored Ed25519 private key identified by the Zetrix address.

```json
{"openapi":"3.1.0","info":{"title":"Zetrix Microservice API","version":"1.0.0"},"tags":[{"name":"HSM","description":"Hardware Security Module — Thales Luna Cloud (DPoD)"}],"servers":[{"url":"https://public-api-sandbox.zetrix.com"}],"security":[],"paths":{"/api/hsm/sign-message":{"post":{"tags":["HSM"],"summary":"Sign message with HSM","operationId":"signMessageHsm","description":"Signs a UTF-8 message using the HSM-stored Ed25519 private key identified by the Zetrix address.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HsmMessageDataReqDto"}}}},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResponseWrapperListSignerEntity"}}}}}}}},"components":{"schemas":{"HsmMessageDataReqDto":{"type":"object","description":"Request to sign a UTF-8 message using the HSM","properties":{"message":{"type":"string","description":"UTF-8 message to sign"},"password":{"type":"string","description":"User password used to decrypt the stored HSM key label","minLength":8,"maxLength":128},"address":{"type":"string","description":"Zetrix address returned by /hsm/create-account"}},"required":["message","password","address"]},"ResponseWrapperListSignerEntity":{"type":"object","properties":{"object":{"type":"array","items":{"$ref":"#/components/schemas/SignerEntity"}},"messages":{"type":"array","items":{"$ref":"#/components/schemas/ResponseMessage"}},"success":{"type":"boolean"},"timestamp":{"type":"string","format":"date-time"},"traceId":{"type":"string"}}},"SignerEntity":{"type":"object","description":"A signer object containing a signature and public key pair. Used in transaction/contract submission requests.","properties":{"signBlob":{"type":"string","description":"Hex-encoded Ed25519 signature of the transaction blob."},"publicKey":{"type":"string","description":"Hex-encoded Ed25519 public key of the signer. Must be exactly 76 characters.","minLength":76,"maxLength":76}}},"ResponseMessage":{"type":"object","description":"A response message indicating informational, warning, or error details.","properties":{"type":{"type":"string","description":"Severity: `INFO`, `WARNING`, or `ERROR`.","enum":["INFO","ERROR","WARNING"]},"errorCode":{"type":"integer","format":"int32","description":"Numeric error code (0 = no error)."},"message":{"type":"string","description":"Human-readable description."}}}}}}
```