AWS KMS

This guide walks you through using AWS KMS integration as the backing store for keys created via the Enterprise Stack KMS service. It highlights the request payloads, response data, and auth choices you have available based on your setup so you can quickly provision keys that other Enterprise Stack services can reuse.

What you can do

  • Generate new signing keys inside AWS KMS while keeping a synchronized reference in the Enterprise Stack which you can use in other services (e.g. when issuing a verifiable credential).
  • Use various AWS credential options depending on your deployment, such as:
    • Default credential chain when the Enterprise Stack already runs in AWS and can reuse the host-provided identity.
    • Specific IAM role when you want key creation to always run under a designated role attached to the host.
    • Access key pair when operating outside AWS or in environments without IAM roles.

Supported AWS key algorithms

  • secp256r1
  • secp256k1
  • RSA

Create keys in AWS KMS

Every key creation request hits POST /v1/{target}/kms-service-api/keys/generate. What you choose next is how the Enterprise Stack authenticates to AWS KMS:

Step 1 – Select the AWS credential source

ModeBest whenNotes
AWS environment-managed credentialsEnterprise Stack already runs inside AWS with an IAM role/environment profileCredentials stay on the host; requests only need the region.
AWS role nameEnterprise Stack runs on AWS but you need to pin the IAM role used for key creationRole must match the instance profile. Temporary credentials are refreshed automatically.
AWS access keysEnterprise Stack runs outside AWS or cannot rely on instance rolesRotate the key pair regularly; credentials travel with the request.

All modes produce the same output: a reference to a new AWS KMS key that you can immediately reuse in other Enterprise Stack services.

Step 2a – Environment-managed credentials

Choose this when the Enterprise Stack already runs in AWS (EKS, ECS, EC2) and the host provides the credentials (via IAM role, environment profile, or similar). You only send the region in the request; the platform takes care of the rest.

CURL

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

Request

curl -X 'POST' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v1/waltid.tenant1.kms1/kms-service-api/keys/generate' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer {yourToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "backend": "aws",
  "keyType": "secp256r1",
  "config": {
    "region": "eu-central-1"
  }
}'

Body

{
  "backend": "aws",
  "keyType": "secp256r1",
  "config": {
    "region": "eu-central-1"
  }
}

Path Parameters

  • orgID: Org subdomain ({orgID}.enterprise-sandbox.waltid.dev).
  • target: organization.tenant.kmsService[.optionalKeyId], e.g. waltid.tenant1.kms1.

Body Parameters

  • backend: aws.
  • keyType: AWS-supported algorithm (secp256r1, secp256k1, RSA).
  • config.region: AWS region where the key will be created.

Response Example

{
  "_id": "waltid.tenant1.kms1.kms-key-123",
  "key": {
    "type": "aws",
    "config": {
      "region": "eu-central-1"
    },
    "id": "a1b2c3d4-5678-90ab-cdef-EXAMPLE",
    "_keyType": "secp256r1"
  },
  "parent": "waltid.tenant1.kms1"
}

Response Codes

  • 201 Created – Key generated and stored successfully in the KMS.
  • 400 Bad Request – Unsupported backend, invalid key type, or missing backend configuration (as per Swagger).
  • 401 Unauthorized – Authentication required (missing/invalid bearer token).
  • 403 Forbidden – Authenticated but lacking permissions to generate keys in this KMS.

Step 2b – Pinned IAM role

Run this when the Enterprise Stack is on AWS infrastructure but you need to control which IAM role is used for key creation. The service fetches temporary credentials for the provided roleName and keeps them fresh automatically.

CURL

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

Request

curl -X 'POST' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v1/waltid.tenant1.kms1/kms-service-api/keys/generate' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer {yourToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "backend": "aws",
  "keyType": "secp256r1",
  "config": {
    "auth": {
      "roleName": "AccessRole",
      "region": "eu-central-1"
    }
  }
}'

Path Parameters

  • orgID: Org subdomain ({orgID}.enterprise-sandbox.waltid.dev).
  • target: organization.tenant.kmsService[.optionalKeyId], e.g. waltid.tenant1.kms1.

Body Parameters

  • backend: aws.
  • keyType: AWS-compatible algorithm.
  • config.auth.roleName: Name of the IAM role the workload should use.
  • config.auth.region: AWS region where to create the key.

Body

{
  "backend": "aws",
  "keyType": "secp256r1",
  "config": {
    "auth": {
      "roleName": "AccessRole",
      "region": "eu-central-1"
    }
  }
}

Response Example

{
  "_id": "waltid.tenant1.kms1.kms-key-123",
  "key": {
    "type": "aws",
    "config": {
      "auth": {
        "roleName": "AccessRole",
        "region": "eu-central-1"
      }
    },
    "id": "a1b2c3d4-5678-90ab-cdef-EXAMPLE",
    "_keyType": "secp256r1"
  },
  "parent": "waltid.tenant1.kms1"
}

Response Codes

  • 201 Created – Key generated and stored successfully under the specified IAM role.
  • 400 Bad Request – Invalid request (e.g., missing role name or unsupported key type).
  • 401 Unauthorized – Authentication required.
  • 403 Forbidden – Authenticated but not allowed to use the selected IAM role or KMS.

Step 2c – Access key pair

Use this when the Enterprise Stack runs outside AWS (on-prem, another cloud, local) and cannot obtain credentials from the host. You provide an IAM user's access key pair directly in the request. The Enterprise Stack stores the configuration in the KMS entry and uses the supplied keys for AWS calls.

CURL

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

curl -X 'POST' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v1/waltid.tenant1.kms1/kms-service-api/keys/generate' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer {yourToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "backend": "aws-rest-api",
  "keyType": "secp256r1",
  "config": {
    "auth": {
      "accessKeyId": "AKIAIOSFODNN7EXAMPLE",
      "secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
      "region": "eu-central-1"
    }
  }
}'

Path Parameters

  • orgID: Org subdomain ({orgID}.enterprise-sandbox.waltid.dev).
  • target: organization.tenant.kmsService[.optionalKeyId], e.g. waltid.tenant1.kms1.

Body Parameters

  • backend: aws-rest-api.
  • keyType: AWS-compatible algorithm.
  • config.auth.accessKeyId: IAM access key ID with permissions to kms:CreateKey, kms:DescribeKey, etc.
  • config.auth.secretAccessKey: Matching secret key (rotate frequently).
  • config.auth.region: AWS region for the key.

Body

{
  "backend": "aws-rest-api",
  "keyType": "secp256r1",
  "config": {
    "auth": {
      "accessKeyId": "AKIAIOSFODNN7EXAMPLE",
      "secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
      "region": "eu-central-1"
    }
  }
}

Response Example

{
  "_id": "waltid.tenant1.kms1.kms-key-123",
  "key": {
    "type": "aws-rest-api",
    "config": {
      "auth": {
        "accessKeyId": "AKIAIOSFODNN7EXAMPLE",
        "region": "eu-central-1"
      }
    },
    "id": "a1b2c3d4-5678-90ab-cdef-EXAMPLE",
    "_keyType": "secp256r1"
  },
  "parent": "waltid.tenant1.kms1"
}

Response Codes

  • 201 Created – Key generated and stored successfully.
  • 400 Bad Request – Invalid configuration (missing access key fields, unsupported key type, etc.).
  • 401 Unauthorized – Authentication required.
  • 403 Forbidden – Authenticated but lacking permission to generate keys for this KMS.
Last updated on November 26, 2025
Hashicorp VaultOverview