Hold your own key configuration API reference

Note

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

Hold your own key (HYOK) lets you authenticate a key management system with HCP Terraform to encrypt workspace state and plan data with a key that you provide and control.

HCP Terraform lets you configure multiple HYOK configurations for an organization. Each HYOK configuration corresponds to a single key in a KMS. Additional HYOK configurations can point to different keys in the same KMS, or keys in others KMSs.

A HYOK configuration specifies the following in HCP Terraform:

How to authenticate to your KMS using OIDC
Which key from your KMS to use
What name to use to identify this configuration within HCP Terraform

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

Attributes

Attribute	Description
`name`	Label for the HYOK configuration to be used within HCP Terraform
`kek-id`	Refers to the name of your key encryption key stored in your key management service
`kms-options`	Optional object used to specify additional fields for some key management services. Fields include `key_region`, `key_location`, and `key_ring_id`. See table below for more details.
`primary`	Boolean flag that indicates whether this HYOK configuration should be used for HYOK encryption of Terraform artifacts.
`status`	Indicates a HYOK configuration status. This status can be `active`, `testing`, `test_failed`, `available`, `revoking`, or `revoked`. See table below for more details.
`error`	A supplementary error message that provides additional context when the `status` is `errored` or `test_failed`.

HYOK configuration status

The HYOK configuration status is found in data.attributes.status. The following list describes the possible states of a HYOK configuration.

State	Description
`available`	Indicates that the HYOK configuration has been tested and is ready to be used for encryption.
`testing`	Indicates that the HYOK configuration is currently in the process of testing whether your key encryption key can be used to encrypt and decrypt data.
`test_failed`	Indicates that the HYOK configuration was not able to be used fetch your key encryption key and use it to encrypt and decrypt data
`revoked`	Indicates that the HYOK configuration was successfully revoked. If you wish to stop using a key, you may revoke it within HCP Terraform.
`revoking`	Indicates that the HYOK configuration is in the process of being revoked.

KMS options

KMS Options are additional options that can be found in data.attributes.kms-options. The following list describes the possible options for KMS options.

Option	Description
`key_region`	The AWS region where your key is located.
`key_location`	A key ring is the root resource for Google Cloud KMS keys and key versions. Each key ring exists within a given location.
`key_ring_id`	A key ring is the root resource for Google Cloud KMS keys and key versions. Each key ring exists within a given location.

Create an HYOK configuration

POST /organizations/:organization_name/hyok-configurations

Parameter	Description
`organization_name`	The name of the organization

Status	Response	Reason
201	JSON API document	Successfully created a HYOK configuration.
404	JSON API error object	Organization not found, or user unauthorized to perform action.
409	JSON API error object	Conflict; check the error object for more information.
412	JSON API error object	Precondition failed; check the error object for more information.
422	JSON API error object	Malformed request body (missing attributes, wrong types, etc.).

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 `"hyok-configurations"`.
`data.attributes.name`	string		The name for your HYOK configuration
`data.attributes.primary`	boolean		Whether this configuration is the primary configuration to be used for HYOK encryption. Note: only one HYOK configuration can be the primary.
`data.attributes.kek-id`	string		The name or identifier of your key stored in your key management service
`data.relationships.run.organization.id`	string	(nothing)	The ID of the organization to associate with the HYOK configuration.
`data.relationships.run.agent-pool.id`	string	(nothing)	The ID of the agent-pool to associate with the HYOK configuration.
`data.relationships.run.oidc-configuration.id`	string	(nothing)	The ID of the oidc-configuration to associate with the HYOK configuration.

Sample payload

{
  "data": {
    "attributes": {
      "name": "my-key-name",
      "primary": false,
      "kek-id": "key1",
      "status": null,
      "error": null,
      "kms-options": {}
    },
    "relationships": {
      "organization": {
        "data": {
          "type": "organizations",
          "id": "my-hyok-org"
        }
      },
      "agent-pool": {
        "data": {
          "type": "agent-pools",
          "id": "apool-MFtsuFxHkC9pCRgB"
        }
      },
      "oidc-configuration": {
        "data": {
          "type": "vault-oidc-configurations",
          "id": "voidc-dMuFy6AKrawNVBJY"
        }
      }
    },
    "type": "hyok-configurations"
  }
}

Sample request

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

Sample response

{
    "data": {
        "id": "hyokc-L4CxAJEEn8vEUEkj",
        "type": "hyok-configurations",
        "attributes": {
            "kek-id": "key1",
            "kms-options": {},
            "name": "my-key-name",
            "primary": false,
            "status": "untested",
            "error": null
        },
        "relationships": {
            "organization": {
                "data": {
                    "id": "my-hyok-org",
                    "type": "organizations"
                }
            },
            "oidc-configuration": {
                "data": {
                    "id": "voidc-dMuFy6AKrawNVBJY",
                    "type": "vault-oidc-configurations"
                }
            },
            "agent-pool": {
                "data": {
                    "id": "apool-MFtsuFxHkC9pCRgB",
                    "type": "agent-pools"
                }
            },
            "hyok-customer-key-versions": {
                "data": []
            }
        }
    }
}

List HYOK configurations for an organization

GET /api/v2/organizations/:organization_name/hyok-configurations

Parameter	Description
`organization_name`	The name of the organization

Status	Response	Reason
200	JSON API document	Successfully fetched HYOK configurations for the specified organization.
404	JSON API error object	Organization not found, or user unauthorized to perform action.
409	JSON API error object	Conflict; check the error object for more information.
412	JSON API error object	Precondition failed; check the error object for more information.
422	JSON API error object	Malformed request body (missing attributes, wrong types, etc.).

Query parameters

This endpoint supports pagination with standard URL query parameters. Remember to percent-encode [ as %5B and ] as %5D if your tooling doesn't automatically encode URLs.

Parameter	Description
`filter[organization][name]`	Required The name of the organization that owns the desired workspace.
`page[number]`	Optional. If omitted, the endpoint will return the first page.
`page[size]`	Optional. If omitted, the endpoint will return 20 HYOK configurations per page.

Sample request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request GET \
  --data @payload.json \
  https://app.terraform.io/api/v2/organizations/:organization_name/hyok-configuration

Sample response

{
    "data": [
        {
            "id": "hyokc-B4ae7Tzsy52QzMTA",
            "type": "hyok-configurations",
            "attributes": {
                "kek-id": "tf-rocket-hyok-oasis",
                "kms-options": {},
                "name": "tf-rocket-hyok-oasis",
                "primary": true,
                "status": "test_failed",
                "error": "Error forwarding request:: Unexpected response from broker: Status code: 424, Message: Failed Dependency, Organization ID: org-y1xsQ1LBbqpDHiMv, Agent Pool ID: apool-MFtsuFxHkC9pCRgB, Organization ID: org-y1xsQ1LBbqpDHiMv, Agent Pool ID: apool-MFtsuFxHkC9pCRgB"
            },
            "relationships": {
                "organization": {
                    "data": {
                        "id": "my-hyok-org",
                        "type": "organizations"
                    }
                },
                "oidc-configuration": {
                    "data": {
                        "id": "voidc-dMDwrVdzxbWZcjPf",
                        "type": "vault-oidc-configurations"
                    }
                },
                "agent-pool": {
                    "data": {
                        "id": "apool-MFtsuFxHkC9pCRgB",
                        "type": "agent-pools"
                    }
                },
                "hyok-customer-key-versions": {
                    "data": [
                        {
                            "id": "keyv-PJJ5biGx2xGmk1ko",
                            "type": "hyok-customer-key-versions"
                        },
                        {
                            "id": "keyv-mdcFMe2pFHxqTSBq",
                            "type": "hyok-customer-key-versions"
                        },
                        {
                            "id": "keyv-emT4uwmo1B8B81Jt",
                            "type": "hyok-customer-key-versions"
                        },
                        {
                            "id": "keyv-UuRchWcL9fqadq2F",
                            "type": "hyok-customer-key-versions"
                        },
                        {
                            "id": "keyv-tpY5A8Vm883sp9jZ",
                            "type": "hyok-customer-key-versions"
                        },
                        {
                            "id": "keyv-TeELFNmCqpaQ5dNa",
                            "type": "hyok-customer-key-versions"
                        },
                        {
                            "id": "keyv-BeMwZesoPGs3tpNq",
                            "type": "hyok-customer-key-versions"
                        },
                        {
                            "id": "keyv-dLG62jSsAq6o4f8V",
                            "type": "hyok-customer-key-versions"
                        },
                        {
                            "id": "keyv-DjDqHppkyyQ4fgcd",
                            "type": "hyok-customer-key-versions"
                        },
                        {
                            "id": "keyv-pc9SqwDWFkuaYath",
                            "type": "hyok-customer-key-versions"
                        }
                    ]
                }
            }
        },
        {
            "id": "hyokc-L4CxAJEEn8vEUEkj",
            "type": "hyok-configurations",
            "attributes": {
                "kek-id": "key1",
                "kms-options": {},
                "name": "my-key-name",
                "primary": false,
                "status": "test_failed",
                "error": "No Agents are available for request forwarding: Agent Pool ID: apool-MFtsuFxHkC9pCRgB, Organization ID: org-y1xsQ1LBbqpDHiMv,"
            },
            "relationships": {
                "organization": {
                    "data": {
                        "id": "my-hyok-org",
                        "type": "organizations"
                    }
                },
                "oidc-configuration": {
                    "data": {
                        "id": "voidc-dMuFy6AKrawNVBJY",
                        "type": "vault-oidc-configurations"
                    }
                },
                "agent-pool": {
                    "data": {
                        "id": "apool-MFtsuFxHkC9pCRgB",
                        "type": "agent-pools"
                    }
                },
                "hyok-customer-key-versions": {
                    "data": []
                }
            }
        },
        {
            "id": "hyokc-tPLXkKbURnrVvMFs",
            "type": "hyok-configurations",
            "attributes": {
                "kek-id": "tf-rocket-hyok-oasis",
                "kms-options": {},
                "name": "whatever-testing2",
                "primary": false,
                "status": "test_failed",
                "error": "Error on agent: error creating kms client: Put \"https://my-vault-cluster-public-vault-659decf3.b8298d98.z1.hashicorp.cloud:8200/v1/auth/jwt/login\": dial tcp: lookup my-vault-cluster-public-vault-659decf3.b8298d98.z1.hashicorp.cloud on 127.0.0.11:53: no such host"
            },
            "relationships": {
                "organization": {
                    "data": {
                        "id": "my-hyok-org",
                        "type": "organizations"
                    }
                },
                "oidc-configuration": {
                    "data": {
                        "id": "voidc-Tje2BewrPfi5gthY",
                        "type": "vault-oidc-configurations"
                    }
                },
                "agent-pool": {
                    "data": {
                        "id": "apool-MFtsuFxHkC9pCRgB",
                        "type": "agent-pools"
                    }
                },
                "hyok-customer-key-versions": {
                    "data": [
                        {
                            "id": "keyv-bUW9Za7LfRStunTp",
                            "type": "hyok-customer-key-versions"
                        }
                    ]
                }
            }
        }
    ],
    "links": {
        "self": "https://tfcdev-f3054ebe.ngrok.app/api/v2/organizations/my-hyok-org/hyok-configurations?organization_name=my-hyok-org\u0026page%5Bnumber%5D=1\u0026page%5Bsize%5D=20",
        "first": "https://tfcdev-f3054ebe.ngrok.app/api/v2/organizations/my-hyok-org/hyok-configurations?organization_name=my-hyok-org\u0026page%5Bnumber%5D=1\u0026page%5Bsize%5D=20",
        "prev": null,
        "next": null,
        "last": "https://tfcdev-f3054ebe.ngrok.app/api/v2/organizations/my-hyok-org/hyok-configurations?organization_name=my-hyok-org\u0026page%5Bnumber%5D=1\u0026page%5Bsize%5D=20"
    },
    "meta": {
        "pagination": {
            "current-page": 1,
            "page-size": 20,
            "prev-page": null,
            "next-page": null,
            "total-pages": 1,
            "total-count": 15
        }
    }
}

Show HYOK configuration

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

Parameter	Description
`id`	The external id of the hyok-configuration

Status	Response	Reason
200	JSON API document	Successfully fetched HYOK configuration.
404	JSON API error object	HYOK configuration not found, or user unauthorized to perform action.
422	JSON API error object	Malformed request body (missing attributes, wrong types, etc.).

Sample request

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

Sample response

{
    "data": {
        "id": "hyokc-WvptL89g24ixsaVk",
        "type": "hyok-configurations",
        "attributes": {
            "kek-id": "tf-rocket-hyok-oasis",
            "kms-options": {},
            "name": "testingbrother",
            "primary": false,
            "status": "untested",
            "error": null
        },
        "relationships": {
            "organization": {
                "data": {
                    "id": "my-hyok-org",
                    "type": "organizations"
                }
            },
            "oidc-configuration": {
                "data": {
                    "id": "voidc-QPuDM2pjRRr3yYkh",
                    "type": "vault-oidc-configurations"
                }
            },
            "agent-pool": {
                "data": {
                    "id": "apool-MFtsuFxHkC9pCRgB",
                    "type": "agent-pools"
                }
            },
            "hyok-customer-key-versions": {
                "data": []
            }
        }
    }
}

Revoke HYOK configuration

POST /api/v2/hyok-customer-key-versions/:id/actions/revoke

Parameter	Description
`id`	The external id of the hyok-customer-key-version

Status	Response	Reason
202	[No content][]	Successfully revoked a HYOK configuration.
404	JSON API error object	HYOK configuration not found, or user unauthorized to perform action.
409	JSON API error object	Conflict; check the error object for more information.
422	JSON API error object	No agent running, malformed request body (missing attributes, wrong types, etc.).

Sample payload

{}

Sample request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://app.terraform.io/api/v2/hyok-customer-key-versions/:id/actions/revoke

Sample response

HTTP/1.1 202 Accepted
Content-Length: 0

Delete HYOK configuration

DELETE /api/v2/hyok-configurations/:id

Parameter	Description
`id`	The external id of the hyok-configuration

Status	Response	Reason
204	[No content][]	Successfully revoked a HYOK configuration.
404	JSON API error object	HYOK configuration not found, or user unauthorized to perform action.

Sample request

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

Sample response

HTTP/1.1 204 No Content
Content-Length: 0

Test persisted HYOK configuration

POST /api/v2/hyok-configurations/:id/actions/test

Parameter	Description
`id`	The external id of the hyok-configuration

Status	Response	Reason
204	[No content][]	Successfully tested a HYOK configuration.
404	JSON API error object	HYOK configuration not found, or user unauthorized to perform action.
422	JSON API error object	No agent running, malformed request body (missing attributes, wrong types, etc.).

Sample payload

{}

Sample request

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

Sample response

HTTP/1.1 204 No Content
Content-Length: 0

Test unpersisted HYOK configuration

POST /api/v2/organizations/:organization_name/hyok-configurations/test

Parameter	Description
`organization_name`	The name of the organization

Status	Response	Reason
204	[No content][]	Successfully tested a HYOK configuration.
404	JSON API error object	HYOK configuration not found, or user unauthorized to perform action.
422	JSON API error object	No agent running, malformed request body (missing attributes, wrong types, etc.).

Sample payload

{
  "hyok-configuration": {
    "data": {
      "attributes": {
        "name": "hyok-config-name",
        "primary": false,
        "kek-id": "keyname1",
        "status": null,
        "error": null,
        "kms-options": {}
      },
      "relationships": {
        "organization": {
          "data": {
            "type": "organizations",
            "id": "my-hyok-org"
          }
        },
        "agent-pool": {
          "data": {
            "type": "agent-pools",
            "id": "apool-MFtsuFxHkC9pCRgB"
          }
        }
      },
      "type": "hyok-configurations"
    }
  },
  "oidc-configuration": {
    "data": {
      "attributes": {
        "address": "https://my-vault-cluster-public-vault-659decf3.b8298d98.z1.hashicorp.cloud:8200",
        "role": "tf-rocket-hyok-role-oasis",
        "namespace": "admin",
        "auth-path": "jwt",
        "encoded-cacert": null
      },
      "relationships": {
        "organization": {
          "data": {
            "type": "organizations",
            "id": "my-hyok-org"
          }
        }
      },
      "type": "vault-oidc-configurations"
    }
  }
}

Sample request

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

Sample response

HTTP/1.1 204 No Content
Content-Length: 0