Local

When using the local configuration for the Key Management Service (KMS), all key information is stored in the Enterprise Stack database. This option is ideal for getting started since it doesn't require any external dependencies. However, for production use cases, we recommend using an external KMS solution. This approach ensures that your secrets remain secure and are not exposed outside of a protected environment, which helps reduce the risk of key compromises.

Key Algorithms Supported
The local KMS configuration allows the creation of these key types:

  • ed25519
  • secp256k1
  • secp256r1
  • RSA
CURL

Endpoint: /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: */*' \
  -H 'Authorization: Bearer {yourToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "kms"
}'

Body

{
  "type": "kms"
}

Path Parameters

  • orgID: - When performing operations within an organization, it is essential to use the organization's Base URL or another valid host alias. For example, if your organization is named test, your default Base URL will be test.enterprise-sandbox.walt.dev when using the sandbox environment.
  • target: resourceIdentifier - The target indicates the organization + tenant in which to create the new KMS service and the service's ID ({organizationID}.{tenantID}.[NewKmsServiceID]), e.g. waltid.tenant1.kms1

Body Parameters

  • type: serviceType - Specifies the type of service to create. In our case kms

Response Codes

  • 201 - Service created successfully.

Create Key

CURL

Endpoint: /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: */*' \
  -H 'Authorization: Bearer {yourToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "backend": "jwk",
  "keyType": "Ed25519"
}'

Body

{
  "backend": "jwk",
  "keyType": "Ed25519"
}

Path Parameters

  • orgID: - When performing operations within an organization, it is essential to use the organization's Base URL or another valid host alias. For example, if your organization is named test, your default Base URL will be test.enterprise-sandbox.walt.dev when using the sandbox environment.
  • target: resourceIdentifier - The target indicates the organization + tenant + kmsService in which to create the new key and the key's ID ({organizationID}.{tenantID}.{kmsServiceID}.[newKeyID]), e.g. waltid.tenant1.kms1.key1

Body Parameters

  • backend: String - Specifies the storage type of key. jwk means the local storage option is used and the key is stored in the Enterprise Stack backend.
  • keyType: String - the algorithm used to generate the key. For local, it can be ed25519, secp256k1, secp256r1, or RSA. Generation does not set use, so the key may perform every operation that key type supports. Import a JWK with use when the key must be limited to signing or to encryption.

Response

201 - Key created successfully.

{
  "_id": "waltid.tenant1.kms1.key1",
  "key": {
    "type": "jwk",
    "jwk": {
      "kty": "OKP",
      "d": "ywmoRVTD9fexMtGW0lKE3o9_0ulfzGXr9xHGL0lPhhA",
      "crv": "Ed25519",
      "kid": "IQO7DILxtagpTLXkuHkRkJURb2GqcUIwXYZAcGwW1AU",
      "x": "JOsiIE7ME9UZ8y2H-P5RSuYAUiIfs1ywtdBjMGN7I5s"
    }
  },
  "parent": "waltid.tenant1.kms1"
}

Restrict a JWK with use

use is optional. When it is absent, Enterprise allows every operation the key type supports. A P-256 key can then sign and perform key agreement. Ed25519 can sign and verify.

Set use on an imported or stored JWK to limit those operations:

usePermitted operations
sigSign and verify. The key cannot perform key agreement.
encEncryption operations. A P-256 key can perform ECDH-ES key agreement and cannot sign.
omittedEvery operation supported by the key type.
Signing
Encryption

Endpoint: /v1/{target}/kms-service-api/keys/import/jwk | API Reference

Example Request

curl -X 'POST' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/kms-service-api/keys/import/jwk' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer {yourToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "kty": "EC",
  "crv": "P-256",
  "use": "sig",
  "d": "sSyXzIV_SAqDcG1Zh-XY18-pVNuIXVOqGUDMpRKFrWs",
  "x": "vY_bjQpiaM52LRcL25_Agv1D2ypmJiyDDsIsYqCDoIc",
  "y": "eWPx0z1AizI04weurWEaVb3I0iRCITdKuLP6gnUpGWU"
}'

Body

{
  "kty": "EC",
  "crv": "P-256",
  "use": "sig",
  "d": "sSyXzIV_SAqDcG1Zh-XY18-pVNuIXVOqGUDMpRKFrWs",
  "x": "vY_bjQpiaM52LRcL25_Agv1D2ypmJiyDDsIsYqCDoIc",
  "y": "eWPx0z1AizI04weurWEaVb3I0iRCITdKuLP6gnUpGWU"
}

Body Parameters

  • use: String - sig allows signing and verification only.

Response Codes

  • 200 - Key imported successfully.
Last updated on November 10, 2026