open-vault/website/source/docs/http/secret/aws/index.html.md

layout	page_title	sidebar_current	description
http	HTTP API	docs-http-secret-aws	This is the API documentation for the Vault AWS secret backend.

AWS Secret Backend HTTP API

This is the API documentation for the Vault AWS secret backend. For general information about the usage and operation of the AWS backend, please see the Vault AWS backend documentation.

This documentation assumes the AWS backend is mounted at the /aws path in Vault. Since it is possible to mount secret backends 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.

• 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

• Querying the EC2 metadata service if the Vault server is on EC2 and has querying capabilities

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

Method	Path	Produces
POST	/aws/config/root	204 (empty body)

Parameters

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

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

• region (string: <required>) – Specifies the AWS region.

Sample Payload

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

Sample Request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    https://vault.rocks/v1/aws/config/root

Configure Lease

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

Method	Path	Produces
POST	/aws/config/lease	204 (empty body)

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

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

Sample Request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    https://vault.rocks/v1/aws/config/lease

Read Lease

This endpoint returns the current lease settings for the AWS secret backend.

Method	Path	Produces
GET	/aws/config/lease	200 application/json

Sample Request

$ curl \
    --header "X-Vault-Token: ..." \
    https://vault.rocks/v1/aws/config/lease

Sample Response

{
  "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	Produces
POST	/aws/roles/:name	204 (empty body)

Parameters

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

• 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

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    https://vault.rocks/v1/aws/roles/example-role

Sample Payloads

Using an inline IAM policy:

{
  "policy": "{\"Version\": \"...\"}",
}

Using an ARN:

{
  "arn": "arn:aws:iam::123456789012:user/David"
}

Read Role

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

Method	Path	Produces
GET	/aws/roles/:name	200 application/json

Parameters

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

Sample Request

$ curl \
    --header "X-Vault-Token: ..." \
    https://vault.rocks/v1/aws/roles/example-role

Sample Responses

For an inline IAM policy:

{
  "data": {
    "policy": "{\"Version\": \"...\"}"
  }
}

For an ARN:

{
  "data": {
    "arn": "arn:aws:iam::123456789012:user/David"
  }
}

List Roles

This endpoint lists all existing roles in the backend.

Method	Path	Produces
LIST	/aws/roles	200 application/json

Sample Request

$ curl
    --header "X-Vault-Token: ..." \
    --request LIST \
    https://vault.rocks/v1/aws/roles

Sample Response

{
  "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	Produces
DELET	/aws/roles/:name	204 (empty body)

Parameters

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

Sample Request

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    https://vault.rocks/v1/aws/roles/example-role

Generate IAM Credentials

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

Method	Path	Produces
GET	/aws/creds/:name	200 application/json

Parameters

• name (string: <required>) – Specifies the name of the role to generate credentials againts. This is part of the request URL.

Sample Request

$ curl \
    --header "X-Vault-Token: ..." \
    https://vault.rocks/v1/aws/creds/example-role

Sample Response

{
  "data": {
    "access_key": "AKIA...",
    "secret_key": "xlCs...",
    "security_token": null
  }
}

Generate IAM with STS

This generates a dynamic IAM credential with an STS token based on the named role.

Method	Path	Produces
POST	/aws/sts/:name	204 (empty body)

Parameters

• name (string: <required>) – Specifies the name of the role against which to create this STS credential. This is part of the request URL.

• ttl (string: "3600s") – Specifies the TTL for the use of the STS token. This is specified as a string with a duration suffix.

Sample Payload

{
  "ttl": "5m"
}

Sample Request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    https://vault.rocks/v1/aws/sts/example-role

Sample Response

{
  "data": {
    "access_key": "AKIA...",
    "secret_key": "xlCs...",
    "security_token": "429255"
  }
}