Terraform
Vault 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 Vault OIDC configuration is the model that lets you configure how hold your own key (HYOK) in HCP Terraform connects to your HashiCorp Vault keys.
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 "vault-oidc-configurations" . | |
data.attributes.address | string | The full address of your Vault instance. | |
data.attributes.role | string | The name of a role in your Vault JWT auth path, with permission to encrypt and decrypt with a Transit secrets engine key | |
data.attributes.namespace | string | The namespace your JWT auth path is mounted in. | |
data.attributes.auth-path | string | "jwt" | The mounting path of JWT auth path of JWT auth. Defaults to "jwt" |
data.attributes.encoded-cacert | string | (Optional) A base64 encoded certificate which can be used to authenticate your Vault certificate. Only needed for self-hosted Vault Enterprise instances with a self-signed certificate. |
Sample payload
{
"data": {
"attributes": {
"address": "https://my-vault-cluster-public-vault-659decf3.b8298d98.z1.hashicorp.cloud:8200",
"role": "vault-role-name",
"namespace": "admin",
"auth-path": "jwt-auth-path",
"encoded-cacert": null
},
"type": "vault-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": "voidc-VFmgsjV7WQHqZ8XC",
"type": "vault-oidc-configurations",
"attributes": {
"type": "VaultOidcConfiguration",
"address": "https://my-vault-cluster-public-vault-659decf3.b8298d98.z1.hashicorp.cloud:8200",
"role": "vault-role-name",
"namespace": "admin",
"auth-path": "jwt-auth-path",
"encoded-cacert": null
},
"relationships": {
"organization": {
"data": {
"id": "my-hyok-org",
"type": "organizations"
}
}
},
"links": {
"self": "/api/v2/oidc-configurations/voidc-VFmgsjV7WQHqZ8XC"
}
}
}
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": "voidc-8AVxvZyDs3BqysmB",
"type": "vault-oidc-configurations",
"attributes": {
"type": "VaultOidcConfiguration",
"address": "https://my-vault-cluster-public-vault-659decf3.b8298d98.z1.hashicorp.cloud:8200",
"role": "tf-rocket-hyok-role-oasis",
"namespace": "admin",
"auth-path": "jwt-path",
"encoded-cacert": null
},
"relationships": {
"organization": {
"data": {
"id": "my-hyok-org",
"type": "organizations"
}
}
},
"links": {
"self": "/api/v2/oidc-configurations/voidc-8AVxvZyDs3BqysmB"
}
}
}