open-vault/website/content/api-docs/secret/aws.mdx

---
layout: api
page_title: AWS - Secrets Engines - HTTP API
description: This is the API documentation for the Vault AWS secrets engine.
---

# AWS Secrets Engine (API)

This is the API documentation for the Vault AWS secrets engine. For general
information about the usage and operation of the AWS secrets engine, please see
the [Vault AWS documentation](/docs/secrets/aws).

This documentation assumes the AWS secrets engine is enabled at the `/aws` path
in Vault. Since it is possible to enable secrets engines at any location, please
update your API calls accordingly.

## Configure Root IAM Credentials

This endpoint configures the root IAM credentials to communicate with AWS. There
are multiple ways to pass root IAM credentials to the Vault server, specified
below with the highest precedence first. If credentials already exist, this will
overwrite them.

The official AWS SDK is used for sourcing credentials from env vars, shared
files, or IAM/ECS instances.

- Static credentials provided to the API as a payload

- Credentials in the `AWS_ACCESS_KEY`, `AWS_SECRET_KEY`, and `AWS_REGION`
  environment variables **on the server**

- Shared credentials files

- Assigned IAM role or ECS task role credentials

At present, this endpoint does not confirm that the provided AWS credentials are
valid AWS credentials with proper permissions.

| Method | Path               |
| :----- | :----------------- |
| `POST` | `/aws/config/root` |

### Parameters

- `max_retries` `(int: -1)` - Number of max retries the client should use for
  recoverable errors. The default (`-1`) falls back to the AWS SDK's default
  behavior.

- `access_key` `(string: <required>)` – Specifies the AWS access key ID.

- `secret_key` `(string: <required>)` – Specifies the AWS secret access key.

- `region` `(string: <optional>)` – Specifies the AWS region. If not set it
  will use the `AWS_REGION` env var, `AWS_DEFAULT_REGION` env var, or
  `us-east-1` in that order.

- `iam_endpoint` `(string: <optional>)` – Specifies a custom HTTP IAM endpoint to use.

- `sts_endpoint` `(string: <optional>)` – Specifies a custom HTTP STS endpoint to use.

- `username_template` `(string: <optional>)` - [Template](/docs/concepts/username-templating) describing how
  dynamic usernames are generated. The username template is used to generate both IAM usernames (capped at 64 characters)
  and STS usernames (capped at 32 characters). Longer usernames result in a 500 error.

  To ensure generated usernames are within length limits for both STS/IAM, the template must adequately handle
  both conditional cases (see [Conditional Templates](https://pkg.go.dev/text/template)). As an example, if no template
  is provided the field defaults to the template:

  ```
  {{ if (eq .Type "STS") }}
      {{ printf "vault-%s-%s" (unix_time) (random 20) | truncate 32 }}
  {{ else }}
      {{ printf "vault-%s-%s-%s" (printf "%s-%s" (.DisplayName) (.PolicyName) | truncate 42) (unix_time) (random 20) | truncate 64 }}
  {{ end }}
  ```

### Sample Payload

```json
{
  "access_key": "AKIA...",
  "secret_key": "2J+...",
  "region": "us-east-1"
}
```

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/aws/config/root
```

## Read Root Configuration

This endpoint allows you to read non-secure values that have been configured in the
`config/root` endpoint. In particular, the `secret_key` parameter is never returned.

| Method | Path               |
| :----- | :----------------- |
| `GET`  | `/aws/config/root` |

### Sample Request

```shell-session
$ curl
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/aws/config/root

```

### Sample Response

```json
{
  "data": {
    "access_key": "AKIAEXAMPLE",
    "region": "us-west-2",
    "iam_endpoint": "https://iam.amazonaws.com",
    "sts_endpoint": "https://sts.us-west-2.amazonaws.com",
    "max_retries": -1
  }
}
```

## Rotate Root IAM Credentials

When you have configured Vault with static credentials, you can use this
endpoint to have Vault rotate the access key it used. Note that, due to AWS
eventual consistency, after calling this endpoint, subsequent calls from Vault
to AWS may fail for a few seconds until AWS becomes consistent again.

In order to call this endpoint, Vault's AWS access key MUST be the only access
key on the IAM user; otherwise, generation of a new access key will fail. Once
this method is called, Vault will now be the only entity that knows the AWS
secret key is used to access AWS.

| Method | Path                      |
| :----- | :------------------------ |
| `POST` | `/aws/config/rotate-root` |

### Parameters

There are no parameters to this operation.

### Sample Request

```shell-session
$ curl \
  --header "X-Vault-Token: ..." \
  --request POST \
  http://127.0.0.1:8200/v1/aws/config/rotate-root
```

### Sample Response

```json
{
  "data": {
    "access_key": "AKIA..."
  }
}
```

The new access key Vault uses is returned by this operation.

## Configure Lease

This endpoint configures lease settings for the AWS secrets engine. It is
optional, as there are default values for `lease` and `lease_max`.

| Method | Path                |
| :----- | :------------------ |
| `POST` | `/aws/config/lease` |

### Parameters

- `lease` `(string: <required>)` – Specifies the lease value provided as a
  string duration with time suffix. "h" (hour) is the largest suffix.

- `lease_max` `(string: <required>)` – Specifies the maximum lease value
  provided as a string duration with time suffix. "h" (hour) is the largest
  suffix.

### Sample Payload

```json
{
  "lease": "30m",
  "lease_max": "12h"
}
```

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/aws/config/lease
```

## Read Lease

This endpoint returns the current lease settings for the AWS secrets engine.

| Method | Path                |
| :----- | :------------------ |
| `GET`  | `/aws/config/lease` |

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/aws/config/lease
```

### Sample Response

```json
{
  "data": {
    "lease": "30m0s",
    "lease_max": "12h0m0s"
  }
}
```

## Create/Update Role

This endpoint creates or updates the role with the given `name`. If a role with
the name does not exist, it will be created. If the role exists, it will be
updated with the new attributes.

| Method | Path               |
| :----- | :----------------- |
| `POST` | `/aws/roles/:name` |

### Parameters

- `name` `(string: <required>)` – Specifies the name of the role to create. This
  is part of the request URL.

- `credential_type` `(string: <required>)` – Specifies the type of credential to be used when
  retrieving credentials from the role. Must be one of `iam_user`,
  `assumed_role`, or `federation_token`.

- `role_arns` `(list: [])` – Specifies the ARNs of the AWS roles this Vault role
  is allowed to assume. Required when `credential_type` is `assumed_role` and
  prohibited otherwise. This is a comma-separated string or JSON array.

- `policy_arns` `(list: [])` – Specifies a list of AWS managed policy ARN. The
  behavior depends on the credential type. With `iam_user`, the policies will
  be attached to IAM users when they are requested. With `assumed_role` and
  `federation_token`, the policy ARNs will act as a filter on what the
  credentials can do, similar to `policy_document`.
  When `credential_type` is `iam_user` or `federation_token`, at
  least one of `policy_arns` or `policy_document` must be specified. This is a
  comma-separated string or JSON array.

- `policy_document` `(string)` – The IAM policy document for the role. The
  behavior depends on the credential type. With `iam_user`, the policy document
  will be attached to the IAM user generated and augment the permissions the IAM
  user has. With `assumed_role` and `federation_token`, the policy document will
  act as a filter on what the credentials can do, similar to `policy_arns`.

- `iam_groups` `(list: [])` - A list of IAM group names. IAM users generated
  against this vault role will be added to these IAM Groups. For a credential
  type of `assumed_role` or `federation_token`, the policies sent to the
  corresponding AWS call (sts:AssumeRole or sts:GetFederation) will be the
  policies from each group in `iam_groups` combined with the `policy_document`
  and `policy_arns` parameters.

- `iam_tags` `(list: [])` - A list of strings representing a key/value pair to be used as a
  tag for any `iam_user` user that is created by this role. Format is a key and value
  separated by an `=` (e.g. `test_key=value`). Note: when using the CLI multiple tags
  can be specified in the role configuration by adding another `iam_tags` assignment
  in the same command.

- `default_sts_ttl` `(string)` - The default TTL for STS credentials. When a TTL is not
  specified when STS credentials are requested, and a default TTL is specified
  on the role, then this default TTL will be used. Valid only when
  `credential_type` is one of `assumed_role` or `federation_token`.

- `max_sts_ttl` `(string)` - The max allowed TTL for STS credentials (credentials
  TTL are capped to `max_sts_ttl`). Valid only when `credential_type` is one of
  `assumed_role` or `federation_token`.

- `user_path` `(string)` - The path for the user name. Valid only when
  `credential_type` is `iam_user`. Default is `/`

- `permissions_boundary_arn` `(string)` - The ARN of the [AWS Permissions
  Boundary](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html)
  to attach to IAM users created in the role. Valid only when `credential_type`
  is `iam_user`. If not specified, then no permissions boundary policy will be
  attached.

Legacy parameters:

These parameters are supported for backwards compatibility only. They cannot be
mixed with the parameters listed above.

- `policy` `(string: <required unless arn provided>)` – Specifies the IAM policy
  in JSON format.

- `arn` `(string: <required unless policy provided>)` – Specifies the full ARN
  reference to the desired existing policy.

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/aws/roles/example-role
```

### Sample Payloads

Using an inline IAM policy:

```json
{
  "credential_type": "federation_token",
  "policy_document": "{\"Version\": \"...\"}"
}
```

Using an ARN:

```json
{
  "credential_type": "assumed_role",
  "role_arns": "arn:aws:iam::123456789012:role/DeveloperRole"
}
```

Using groups:

```json
{
  "credential_type": "assumed_role",
  "iam_groups": ["group1", "group2"]
}
```

Using tags:

<Tabs>
  <Tab heading="cURL">

    ```json
    {
      "credential_type": "iam_user",
      "iam_tags": [
        "first_key=first_value",
        "second_key=second_value"
      ]
    }
    ```
    or
    ```json
    {
      "credential_type": "iam_user",
      "iam_tags": {
        "first_key": "first_value",
        "second_key": "second_value"
      }
    }
    ```

  </Tab>
  <Tab heading="CLI">

    ```bash
      vault write aws/roles/example-role \
      credential_type=iam_user \
      iam_tags="first_key=first_value" \
      iam_tags="second_key=second_value" \
    ```
    or
    ```bash
      vault write aws/roles/example-role \
      credential_type=iam_user \
      iam_tags=@test.json
    ```
    where test.json is
    ```json
    ["tag1=42", "tag2=something"]
    ```

  </Tab>
</Tabs>

## Read Role

This endpoint queries an existing role by the given name. If the role does not
exist, a 404 is returned.

| Method | Path               |
| :----- | :----------------- |
| `GET`  | `/aws/roles/:name` |

If invalid role data was supplied to the role from an earlier version of Vault,
then it will show up in the response as `invalid_data`.

### Parameters

- `name` `(string: <required>)` – Specifies the name of the role to read. This
  is part of the request URL.

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/aws/roles/example-role
```

### Sample Responses

For an inline IAM policy:

```json
{
  "data": {
    "policy_document": "{\"Version\": \"...\"}",
    "policy_arns": [],
    "credential_types": ["assumed_role"],
    "role_arns": [],
    "iam_groups": []
  }
}
```

For a role ARN:

```json
{
  "data": {
    "policy_document": "",
    "policy_arns": [],
    "credential_types": ["assumed_role"],
    "role_arns": ["arn:aws:iam::123456789012:role/example-role"],
    "iam_groups": []
  }
}
```

For IAM groups:

```json
{
  "data": {
    "policy_document": "",
    "policy_arns": [],
    "credential_types": ["assumed_role"],
    "role_arns": [],
    "iam_groups": ["group1", "group2"]
  }
}
```

## List Roles

This endpoint lists all existing roles in the secrets engine.

| Method | Path         |
| :----- | :----------- |
| `LIST` | `/aws/roles` |

### Sample Request

```shell-session
$ curl
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/aws/roles
```

### Sample Response

```json
{
  "data": {
    "keys": ["example-role"]
  }
}
```

## Delete Role

This endpoint deletes an existing role by the given name. If the role does not
exist, a 404 is returned.

| Method   | Path               |
| :------- | :----------------- |
| `DELETE` | `/aws/roles/:name` |

### Parameters

- `name` `(string: <required>)` – Specifies the name of the role to delete. This
  is part of the request URL.

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/aws/roles/example-role
```

## Generate Credentials

This endpoint generates credentials based on the named role. This role must be
created before queried.

| Method | Path               |
| :----- | :----------------- |
| `GET`  | `/aws/creds/:name` |
| `PUT`  | `/aws/sts/:name`   |

The `/aws/creds` and `/aws/sts` endpoints are almost identical. The exception is
when retrieving credentials for a role that was specified with the legacy `arn`
or `policy` parameter. In this case, credentials retrieved through `/aws/sts`
must be of either the `assumed_role` or `federation_token` types, and
credentials retrieved through `/aws/creds` must be of the `iam_user` type.

### Parameters

- `name` `(string: <required>)` – Specifies the name of the role to generate
  credentials against. This is part of the request URL.
- `role_arn` `(string)` – The ARN of the role to assume if `credential_type` on
  the Vault role is `assumed_role`. Must match one of the allowed role ARNs in
  the Vault role. Optional if the Vault role only allows a single AWS role ARN;
  required otherwise.
- `role_session_name` `(string)` - The role session name to attach to the assumed role ARN.
  `role_session_name` is limited to 64 characters; if exceeded, the `role_session_name` in the
  assumed role ARN will be truncated to 64 characters. If `role_session_name` is not provided,
  then it will be generated dynamically by default.
- `ttl` `(string: "3600s")` – Specifies the TTL for the use of the STS token.
  This is specified as a string with a duration suffix. Valid only when
  `credential_type` is `assumed_role` or `federation_token`. When not specified,
  the `default_sts_ttl` set for the role will be used. If that is also not set, then
  the default value of `3600s` will be used. AWS places limits
  on the maximum TTL allowed. See the AWS documentation on the `DurationSeconds`
  parameter for
  [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)
  (for `assumed_role` credential types) and
  [GetFederationToken](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetFederationToken.html)
  (for `federation_token` credential types) for more details.

### Sample Request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/aws/creds/example-role
```

### Sample Response

```json
{
  "data": {
    "access_key": "AKIA...",
    "secret_key": "xlCs...",
    "security_token": null,
    "arn": "arn:aws:sts::123456789012:assumed-role/DeveloperRole/some-user-supplied-role-session-name"
  }
}
```