AWS OIDC configuration API reference

Note

Hold your own key is available on the HCP Terraform Premium edition. Refer to HCP Terraform pricing for details.

An AWS OIDC configuration is the model that lets you configure how hold your own key (HYOK) in HCP Terraform connects to your AWS Key Management Service keys. Your AWS OIDC configuration includes the AWS role ARN that HCP Terraform assumes to encrypt a data encryption key.

To learn more about hold your own key, refer to the Overview.

Create OIDC configuration

POST /api/v2/organizations/:organization_id/oidc-configurations

Parameter	Description
`:organization_id`	The id of your organization

Status	Response	Reason
201	JSON API document	Successfully created OIDC configuration.
404	JSON API error object	Organization not found, or user unauthorized to perform action.

Request body

This POST endpoint requires a JSON object with the following properties as a request payload.

Properties without a default value are required.

Key path	Type	Default	Description
`data.type`	string		Must be `"aws-oidc-configurations"`.
`data.attributes.role-arn`	string		The AWS arn of your role.

Sample payload

{
  "data": {
    "attributes": {
      "role-arn": "arn:aws:iam::533267421525:role/hyok-staging"
    },
    "type": "aws-oidc-configurations"
  }
}

Sample request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --data @payload.json \
  --request POST \
  https://app.terraform.io/api/v2/organizations/:organization_id/oidc-configurations

Sample response

{
    "data": {
        "id": "awsoidc-EHHrzudV58S9STr5",
        "type": "aws-oidc-configurations",
        "attributes": {
            "type": "AwsOidcConfiguration",
            "role-arn": "arn:aws:iam::533267421525:role/hyok-staging"
        },
        "relationships": {
            "organization": {
                "data": {
                    "id": "my-hyok-org",
                    "type": "organizations"
                }
            }
        },
        "links": {
            "self": "/api/v2/oidc-configurations/awsoidc-EHHrzudV58S9STr5"
        }
    }
}

Show OIDC configuration

GET /api/v2/oidc-configurations/:id

Parameter	Description
`id`	The ID of the OIDC configuration.

Status	Response	Reason
200	JSON API document	Successfully fetched OIDC configuration.
404	JSON API error object	OIDC configuration not found, or user unauthorized to perform action.

Sample request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request GET \
  https://app.terraform.io/api/v2/oidc-configurations/:id

Sample response

{
    "data": {
        "id": "awsoidc-EHHrzudV58S9STr5",
        "type": "aws-oidc-configurations",
        "attributes": {
            "type": "AwsOidcConfiguration",
            "role-arn": "arn:aws:iam::533267421525:role/hyok-staging"
        },
        "relationships": {
            "organization": {
                "data": {
                    "id": "my-hyok-org",
                    "type": "organizations"
                }
            }
        },
        "links": {
            "self": "/api/v2/oidc-configurations/awsoidc-EHHrzudV58S9STr5"
        }
    }
}