---
layout: api
page_title: AWS KMS - Key Management - Secrets Engines - HTTP API
description: The AWS KMS API documentation for the Key Management secrets engine.
---

# AWS KMS (API)

The Key Management secrets engine supports lifecycle management of keys in [AWS KMS](https://aws.amazon.com/kms/)
regions. This is accomplished by configuring a KMS provider resource with the `awskms` provider and
other provider-specific parameter values.

The following sections provide API documentation that is specific to AWS KMS.

## Create/Update KMS provider

This endpoint creates or updates a KMS provider. If a KMS provider with the given `name`
does not exist, it will be created. If the KMS provider exists, it will be updated with
the given parameter values.

| Method | Path                 |
| :----- | :------------------- |
| `POST` | `/keymgmt/kms/:name` |

### Parameters

- `name` `(string: <required>)` – Specifies the name of the KMS provider to create or update.
  This is provided as part of the request URL.

- `provider` `(string: <required>)` – Specifies the name of a KMS provider that's external to
  Vault. Must be set to `awskms`. Cannot be changed after creation.

- `key_collection` `(string: <required>)` – Refers to the name of an AWS
  [region](https://aws.amazon.com/about-aws/global-infrastructure/regions_az/?p=ngi&loc=2).
  Cannot be changed after creation.

- `credentials` `(map<string|string>: nil)` – The credentials to use for authentication with
  AWS KMS. Supplying values for this parameter is optional, as credentials may also be specified
  as environment variables. Credentials provided to this parameter will take precedence over
  credentials provided via environment variables.

  - `access_key` `(string: <required>)` - The AWS access key ID. May also be specified
    by the `AWS_ACCESS_KEY_ID` environment variable.
  - `secret_key` `(string: <required>)` - The AWS secret access key. May also be specified
    by the `AWS_SECRET_ACCESS_KEY` environment variable.
  - `session_token` `(string: <optional>)` - The AWS session token. May also be specified
    by the `AWS_SESSION_TOKEN` environment variable.
  - `endpoint` `(string: <optional>)` - The KMS API endpoint to be used to make AWS KMS
    requests. May also be specified by the `AWS_KMS_ENDPOINT` environment variable. This
    is useful when connecting to KMS over a [VPC Endpoint](https://docs.aws.amazon.com/kms/latest/developerguide/kms-vpc-endpoint.html).
    If not set, the secrets engine will use the default API endpoint for the region.