#PKCS#11 HSM

Endpoint: POST /v1/{target}/resource-api/services/create | API Reference

#Example Request

curl -X 'POST' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/resource-api/services/create' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {yourToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "kms",
  "configRef": "softhsm"
}'

Path Parameters

• orgID: String (required) - Your organization ID. When performing operations within an organization, use the organization's Base URL. For example, if your organization is named test, your default Base URL will be test.enterprise-sandbox.waltid.dev when using the sandbox environment.
• target: String (required) - The resource identifier indicating the organization + tenant + new KMS service ({organizationID}.{tenantID}.{newKmsServiceID}). Example: waltid.tenant1.hsmkms.

Header Parameters

• Authorization: String (required) - Bearer token for Enterprise Stack authentication. Format: Bearer {token}.

Body Parameters

• type: String (required) - Service type. Must be "kms".
• configRef: String (required) - Profile id from resource-access.conf. Examples: "softhsm", "luna".

Response Codes

• 201 — Service created successfully.
• 401 — Invalid or missing authentication token.

Endpoint: POST /v1/{target}/kms-service-api/keys/generate | API Reference

#Example Request

curl -X 'POST' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/kms-service-api/keys/generate' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {yourToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "backend": "softhsm",
  "keyType": "secp256r1"
}'

For Thales Luna, use "backend": "luna" (matching your profile id).

Path Parameters

• orgID: String (required) - Your organization ID. When performing operations within an organization, use the organization's Base URL. For example, if your organization is named test, your default Base URL will be test.enterprise-sandbox.waltid.dev when using the sandbox environment.
• target: String (required) - The KMS service resource identifier ({organizationID}.{tenantID}.{kmsServiceID}). Example: waltid.tenant1.hsmkms.

Header Parameters

• Authorization: String (required) - Bearer token for Enterprise Stack authentication. Format: Bearer {token}.

Body Parameters

• backend: String (optional) - PKCS#11 profile id from resource-access.conf. Omit if the KMS was created with configRef.
• keyType: String (required) - Algorithm to generate. One of the supported algorithms.

#Example Response

The response is a public JWK only — there is no private key material (d):

{
  "_id": "waltid.tenant1.hsmkms.019fae71-d211-71eb-9e33-e27ffa96c35a",
  "key": {
    "type": "jwk",
    "jwk": {
      "kty": "EC",
      "crv": "P-256",
      "x": "...",
      "y": "..."
    }
  },
  "metadata": {
    "resource-id": "softhsm"
  }
}

Response Fields

• _id: String - Full key path. Use this as {target} for sign, delete, and remove calls.
• key: Object - Public key material only (type: "jwk"). The private key remains on the token.
• metadata.resource-id: String - The resource-access profile id used for this key.

Response Codes

• 201 — Key created on the token and stored in the KMS.
• 400 — Unsupported key type, or the token refused the request.
• 401 — Invalid or missing authentication token.

Endpoint: POST /v1/{target}/kms-service-api/keys/generate | API Reference

#Example Request

curl -X 'POST' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/kms-service-api/keys/generate' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {yourToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "backend": "luna",
  "keyType": "secp256r1",
  "config": {
    "alias": "issuer-signing-key"
  }
}'

Path Parameters

• orgID: String (required) - Your organization ID. When performing operations within an organization, use the organization's Base URL.
• target: String (required) - The KMS service resource identifier ({organizationID}.{tenantID}.{kmsServiceID}). Example: waltid.tenant1.hsmkms.

Header Parameters

• Authorization: String (required) - Bearer token for Enterprise Stack authentication. Format: Bearer {token}.

Body Parameters

• backend: String (optional) - PKCS#11 profile id from resource-access.conf. Omit if the KMS was created with configRef.
• keyType: String (required) - Still required by the API shape; the key's real type is read from the token and must be usable for sign / verify.
• config: Object (required) - Adoption options.
  • alias: String (required) - Alias of an existing private key with a certificate on the token.

Response Codes

• 201 — Existing token key attached and stored in the KMS.
• 400 — Alias missing on the token, or the key has no certificate.
• 401 — Invalid or missing authentication token.

Endpoint: POST /v1/{target}/kms-service-api/keys/sign | API Reference

#Example Request

curl -X 'POST' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/kms-service-api/keys/sign' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {yourToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "plaintext": "hello from the HSM"
}'

Path Parameters

• orgID: String (required) - Your organization ID. When performing operations within an organization, use the organization's Base URL.
• target: String (required) - Full key path returned as _id from keys/generate. Example: waltid.tenant1.hsmkms.019fae71-d211-71eb-9e33-e27ffa96c35a.

Header Parameters

• Authorization: String (required) - Bearer token for Enterprise Stack authentication. Format: Bearer {token}.

Body Parameters

• plaintext: String (required) - The message to sign.

#Example Response

{
  "signature": "MEYCIQ..."
}

Response Fields

• signature: String - Base64-encoded signature produced on the token.

Response Codes

• 200 — Signature created successfully.
• 401 — Invalid or missing authentication token.