Configuration — SenseCrypt eID Docs

SenseCrypt Face PKI enables the server to act as a Certificate Authority, issuing and verifying X.509-style face certificates — credentials cryptographically bound to a user's face biometric. To enable this, the server must be configured with a PKI_PRIVATE_KEY.

In v4.0.0, the Face PKI key (PKI_PRIVATE_KEY) and the SensePrint signing key (ISSUERS_PRIVATE_KEY) are two separate configurations with distinct purposes. See the Server Configuration page for details on both.

Required Configuration

For SenseCrypt Face PKI features to work, you must configure pki_private_key before starting the server.

Option 1 — secrets.json:

 {
    "pki_private_key": "<base64-encoded private key>"
  }

Option 2 — environment variable:

export PKI_PRIVATE_KEY=<base64-encoded private key>

Both Secp256k1 and ML-DSA key types are supported. The server auto-detects the key type on startup.

Which Endpoints Require PKI_PRIVATE_KEY:

Endpoint	Requires PKI_PRIVATE_KEY
POST /generate-face-certificate	Yes
GET /root-certificate	Yes
POST /verify-face-certificate	Yes
POST /verify-face-signature	Yes
POST /encrypt-with-face-certificate	Yes
POST /face-decrypt	Yes
POST /face-sign	No
POST /face-public-key	No
POST /verify-face-signature-with-public-key	No

Error When Key Is Not Set - If a certificate-dependent endpoint is called without PKI_PRIVATE_KEY configured, the server returns:

 HTTP 403
  {
    "code": "ERR_PKI_PRIVATE_KEY_NOT_SET",
    "message": "The PKI private key is not set. Please set the PKI private key before attempting
  this operation."
  }

For GET /root-certificate specifically, the response is:

 HTTP 404
  {
    "code": "ERR_ROOT_CERTIFICATE_NOT_FOUND"
  }

Root CA Certificate

Once PKI_PRIVATE_KEY is configured, the server's root CA certificate can be retrieved at any time via GET /root-certificate. Third parties can use this certificate to independently verify face certificates issued by your server without needing access to the private key.

If you want to independently generate a key-pair (without using the installation script), it is described here.