Select your cookie preferences

We use essential cookies and similar tools that are necessary to provide our site and services. We use performance cookies to collect anonymous statistics, so we can understand how customers use our site and make improvements. Essential cookies cannot be deactivated, but you can choose “Customize” or “Decline” to decline performance cookies.

If you agree, AWS and approved third parties will also use cookies to provide useful site features, remember your preferences, and display relevant content, including relevant advertising. To accept or decline all non-essential cookies, choose “Accept” or “Decline.” To make more detailed choices, choose “Customize.”

Testing your permissions

Focus mode
Testing your permissions - AWS Key Management Service

To use AWS KMS, you must have credentials that AWS can use to authenticate your API requests. The credentials must include the permission to access KMS keys and aliases. The permissions are determined by key policies, IAM policies, grants, and cross-account access controls. In addition to controlling access to KMS keys, you can control access to your CloudHSM, and to your custom key stores.

You can specify the DryRun API parameter to verify that you have the necessary permissions to use AWS KMS keys. You can also use DryRun to verify that the request parameters in a AWS KMS API call are correctly specified.

What is the DryRun parameter?

DryRun is an optional API parameter that you specify to verify that AWS KMS API calls will succeed. Use DryRun to test your API call, before actually making the call to AWS KMS. You can verify the following.

  • That you have the necessary permissions to use AWS KMS keys.

  • That you have specified the parameters in the call correctly.

AWS KMS supports using the DryRun parameter in certain API actions:

Using the DryRun parameter will incur charges and will be billed as a standard API request. For more information about AWS KMS pricing, see AWS Key Management Service Pricing.

All API requests using the DryRun parameter apply to the request quota of the API and can result in a throttling exception if you exceed an API request quota. For example, calling Decrypt with DryRun or without DryRun counts against the same cryptographic operations quota. See Throttling AWS KMS requests to learn more.

Every call to an AWS KMS API operation is captured as an event and recorded in an AWS CloudTrail log. The output of any operations that specify the DryRun parameter appear in your CloudTrail log. For more information, see Logging AWS KMS API calls with AWS CloudTrail.

Specifying DryRun with the API

To use DryRun, specify the —dry-run parameter in AWS CLI commands and AWS KMS API calls that support the parameter. When you do, AWS KMS will verify whether your call will succeed. AWS KMS calls that use DryRun will always fail and return a message with information about reason why the call failed. The message can include the following exceptions:

  • DryRunOperationException ‐ The request would succeed if DryRun wasn’t specified.

  • ValidationException ‐ The request failed from specifying an incorrect API parameter.

  • AccessDeniedException ‐ You do not have permissions to perform the specified API action on the KMS resource.

For example, the following command uses the CreateGrant operation and creates a grant that allows users who are authorized to assume the keyUserRole role to call the Decrypt operation on a specified symmetric KMS key. The DryRun parameter is specified.

$ aws kms create-grant \ --key-id 1234abcd-12ab-34cd-56ef-1234567890ab \ --grantee-principal arn:aws:iam::111122223333:role/keyUserRole \ --operations Decrypt \ --dry-run
PrivacySite termsCookie preferences
© 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved.