canonical: https://jentic.com/apis/amazonaws.com/cloudhsmv2 # AWS CloudHSM V2 Jentic publishes the only available OpenAPI specification for AWS CloudHSM V2, keeping it validated and agent-ready. AWS CloudHSM V2 provides single-tenant, FIPS 140-2 Level 3 hardware security modules in your VPC for generating and using cryptographic keys. Agents can create and manage HSM clusters, provision individual HSMs, take and restore backups, and copy backups across regions. The service is intended for workloads with strict key custody, compliance, or BYOK requirements where AWS KMS multi-tenant HSMs are not sufficient. ## For AI agents Provision and manage dedicated AWS CloudHSM clusters, individual HSMs, and encrypted backups for FIPS 140-2 Level 3 key custody. Backed by 15 cluster, HSM, and backup operations. ## Scope Does not handle key generation or cryptographic operations on the wire, KMS multi-tenant keys, or TLS certificate issuance - use for CloudHSM cluster, HSM, and backup lifecycle management only. ## Capabilities - Create CloudHSM clusters in a target VPC and initialize them with a customer trust anchor - Add or delete individual HSM appliances within a cluster to scale cryptographic capacity - Take, describe, and restore CloudHSM backups, including modifying backup retention - Copy CloudHSM backups to a second AWS region for disaster recovery - Tag CloudHSM clusters and backups for cost allocation and access policies - Modify cluster attributes such as backup retention policy after initial provisioning ## Use cases ### FIPS 140-2 Level 3 Key Custody for Regulated Workloads Financial services, healthcare, and government workloads that must hold cryptographic keys in FIPS 140-2 Level 3 hardware can use CloudHSM V2 to provision dedicated HSM clusters inside a VPC. The API creates the cluster, attaches HSMs, and manages the backup lifecycle, so an agent can stand up compliant key storage without console clicks. Typical clusters use 2-3 HSMs across availability zones for high availability. Example prompt: Create a CloudHSM cluster in subnets subnet-aaa and subnet-bbb, then add two HSMs to the cluster ### Cross-Region Disaster Recovery for Cryptographic Material Use CopyBackupToRegion to replicate a CloudHSM backup from a primary region to a secondary region so that a new cluster can be restored from it if the primary region becomes unavailable. The API supports listing backups, modifying retention attributes, and restoring backups marked for deletion within their retention window. This pattern is required by many DR runbooks for HSM-protected workloads. Example prompt: Copy backup backup-1234 from us-east-1 to us-west-2 and verify the destination backup reaches READY state ### Programmatic HSM Fleet Tagging and Inventory Operations teams managing many CloudHSM clusters across accounts can use ListTags, TagResource, and UntagResource to enforce a tagging standard for cost allocation, ownership, and compliance scope. DescribeClusters and DescribeBackups expose cluster state and backup metadata so an agent can produce an up-to-date inventory of HSM resources and their lifecycle status. Example prompt: List all CloudHSM clusters in the current account and tag any without a CostCenter tag with CostCenter=unassigned ### AI Agent Integration via Jentic Through Jentic, an AI agent uses the CloudHSM V2 API by searching for an intent like 'create a CloudHSM cluster', loading the schema for CreateCluster, and executing the call with VPC subnet IDs and HSM type. The agent never sees raw AWS access keys - Jentic signs the SigV4 request server-side using credentials stored in your Jentic One instance. Example prompt: Search Jentic for 'create a CloudHSM cluster', load the CreateCluster schema, and execute it for HSM type hsm1.medium in the supplied subnet IDs ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | /#X-Amz-Target=BaldrApiService.CreateCluster | Create a CloudHSM cluster in a VPC | | POST | /#X-Amz-Target=BaldrApiService.CreateHsm | Provision an HSM inside an existing cluster | | POST | /#X-Amz-Target=BaldrApiService.InitializeCluster | Initialize a cluster with a signed trust anchor | | POST | /#X-Amz-Target=BaldrApiService.DescribeClusters | List and describe CloudHSM clusters | | POST | /#X-Amz-Target=BaldrApiService.DescribeBackups | List backups for clusters in the account | | POST | /#X-Amz-Target=BaldrApiService.CopyBackupToRegion | Copy a backup to a second region for DR | | POST | /#X-Amz-Target=BaldrApiService.RestoreBackup | Restore a backup pending deletion | | POST | /#X-Amz-Target=BaldrApiService.DeleteCluster | Delete an empty CloudHSM cluster | ## Key resources - **Cluster** — Create, describe, modify, and delete CloudHSM clusters inside a VPC - **HSM** — Add or remove individual HSM appliances within a cluster - **Backup** — Describe, restore, modify, and copy cluster backups across regions - **Tag** — Tag CloudHSM clusters and backups for cost allocation and access policies ## Why Jentic - **Setup:** Wiring AWS CloudHSM V2 by hand means holding an access key ID and secret access key, computing an AWS Signature Version 4 signature per request, resolving the correct regional cloudhsmv2 host with the right X-Amz-Target action header, and polling cluster state and handling retries yourself. Through Jentic you install once, import AWS CloudHSM V2 from the API Directory, store the AWS access key once, and your agent calls it. - **Permission scoping:** CloudHSM V2 sends the cluster, HSM, and backup identifiers in the request body rather than the URL path, so scope your agent by the operations it needs, such as creating a cluster or describing clusters. You choose which operations it may call, so destructive ones like deleting a cluster or restoring a backup are not included unless you add them. - **Credential handling:** Your AWS access key ID and secret access key are stored once, encrypted, by your own Jentic One instance, and the Signature Version 4 signature is computed at execution time. The raw keys never enter the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'create a CloudHSM cluster' or 'copy an HSM backup to another region', and Jentic returns the matching CloudHSM V2 operation with its input schema so the agent calls the right action without crawling the AWS reference. ## Related APIs - **AWS Certificate Manager** — ACM issues and manages public and private TLS certificates that often consume keys protected by CloudHSM - **AWS Security Hub** — Security Hub aggregates compliance findings, including controls that verify HSM-backed key usage - **Amazon GuardDuty** — GuardDuty detects suspicious activity in the AWS account hosting the CloudHSM cluster ## FAQ ### Why is there no official OpenAPI spec for AWS CloudHSM V2? AWS does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call AWS CloudHSM V2 via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer. ### What authentication does the AWS CloudHSM V2 API use? CloudHSM V2 uses AWS Signature Version 4 (HMAC) signed requests with an IAM access key ID and secret key, plus a session token if using temporary credentials. Through Jentic, those credentials live in your Jentic One instance and the SigV4 signature is computed server-side, so the agent context never contains the raw secret. ### Can I create and initialize a CloudHSM cluster with this API? Yes. Call CreateCluster with a list of VPC subnet IDs and an HSM type, then call CreateHsm to add HSM appliances, and finally InitializeCluster with a signed certificate from your customer CA to bring the cluster to ACTIVE state. ### How do I take and copy a CloudHSM backup across regions? Backups are taken automatically on cluster changes. Use DescribeBackups to find the backup ID, then call CopyBackupToRegion with the destination region to replicate it. The destination backup gets a new BackupId you can later pass to a CreateCluster SourceBackupId in that region. ### What are the rate limits for the AWS CloudHSM V2 API? AWS CloudHSM V2 enforces standard AWS service throttling - most control-plane calls (CreateCluster, CreateHsm, DescribeBackups) are limited to a small number of TPS per account per region, and throttled responses return ThrottlingException. Use exponential backoff; the AWS SDKs that Jentic wraps already implement this. ### How do I provision a CloudHSM cluster with an AI agent through Jentic? Run pip install jentic, then have the agent search for 'create a CloudHSM cluster', load the CreateCluster schema, and execute it with the SubnetIds and HsmType parameters. Follow with CreateHsm for each HSM and DescribeClusters to poll for ACTIVE state. ### Can I limit what my agent is allowed to do with the AWS CloudHSM V2 API? Yes. Because you run Jentic One yourself, you decide which CloudHSM V2 operations your agent may call, so you can grant read-only actions like DescribeClusters and DescribeBackups while leaving out cluster and HSM creation. Since CloudHSM V2 passes cluster, HSM, and backup identifiers in the request body rather than the URL, scoping is done by operation: destructive calls such as DeleteCluster or RestoreBackup are excluded unless you explicitly add them. Your AWS access key stays in your own Jentic One instance and the request is signed at execution time, so the agent only ever exercises the operations you approve.