Reserved Tag Keys API
Use the /reserved-tag-keys
API endpoints to define and manage tag keys that
have special meaning for your organization. Reserving tag keys enable project
and workspace managers to follow a consistent tagging strategy across the
organization. You can also use them to provide project managers with a means of
disabling overrides for inherited tags.
The following table describes the available endpoints:
Method | Path | Description |
---|---|---|
GET | /organizations/:organization_name/reserved-tag-keys | List reserved tag keys for the specified organization. |
POST | /organizations/:organization_name/reserved-tag-keys | Add a reserved tag key to the specified organization. |
PATCH | /reserved-tags/:reserved_tag_key_id | Update a reserved tag key with the specified ID. |
DELETE | /reserved-tags/:reserved_tag_key_id | Delete a reserved tag key with the specified ID. |
Path parameters
The /reserved-tag-keys/
API endpoints require the following path parameters:
Parameter | Description |
---|---|
:reserved_tag_key_id | The external ID of the reserved tag key. |
:organization_name | The name of the organization containing the reserved tags. |
List reserved tag keys
GET /organizations/:organization_name/reserved-tag-keys
Sample payload
This endpoint does not require a payload.
Sample request
$ curl \ --header "Authorization: Bearer $TOKEN" \ --header "Content-Type: application/vnd.api+json" \ --request GET \ https://app.terraform.io/api/v2/organizations/my-organization/reserved-tag-keys
Sample response
{ "data": [ { "id": "rtk-jjnTseo8NN1jACbk", "type": "reserved-tag-keys", "attributes": { "key": "environment", "disable-overrides": false, "created-at": "2024-08-13T23:06:42.523Z", "updated-at": "2024-08-13T23:06:42.523Z" } }, { "id": "rtk-F1s7kKUShAQxhA1b", "type": "reserved-tag-keys", "attributes": { "key": "cost-center", "disable-overrides": false, "created-at": "2024-08-13T23:06:51.445Z", "updated-at": "2024-08-13T23:06:51.445Z" } }, ], "links": { "self": "https://app.terraform.io/api/v2/organizations/my-organization/reserved-tag-keys?page%5Bnumber%5D=1&page%5Bsize%5D=20", "first": "https://app.terraform.io/api/v2/organizations/my-organization/reserved-tag-keys?page%5Bnumber%5D=1&page%5Bsize%5D=20", "prev": null, "next": null, "last": "https://app.terraform.io/api/v2/organizations/my-organization/reserved-tag-keys?page%5Bnumber%5D=1&page%5Bsize%5D=20" }, "meta": { "pagination": { "current-page": 1, "page-size": 20, "prev-page": null, "next-page": null, "total-pages": 1, "total-count": 2 } }}
Create a reserved tag key
POST /organizations/:organization_name/reserved-tag-keys
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 | none | Must be reserved-tag-keys . |
data.attributes.key | string | none | The key targeted by this reserved |
tag key. | |||
data.attributes.disable-overrides | boolean | none | If true , disables |
overriding inherited tags with the specified key at the workspace level. |
Sample payload
{ "data": { "type": "reserved-tag-keys", "attributes": { "key": "environment", "disable-overrides": false } }}
Sample request
$ curl \ --header "Authorization: Bearer $TOKEN" \ --header "Content-Type: application/vnd.api+json" \ --request POST \ https://app.terraform.io/api/v2/organizations/${ORGANIZATION_NAME}/reserved-tag-keys
Sample response
{ "data": { "id": "rtk-Tj86UdGahKGDiYXY", "type": "reserved-tag-keys", "attributes": { "key": "environment", "disable-overrides": false, "created-at": "2024-09-04T05:02:06.794Z", "updated-at": "2024-09-04T05:02:06.794Z" } }}
Update a reserved tag key
PATCH /reserved-tags/:reserved_tag_key_id
This PATCH 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 | none | Must be reserved-tag-keys . |
data.attributes.key | string | none | The key targeted by this reserved |
tag key. | |||
data.attributes.disable-overrides | boolean | none | If true , disables |
overriding inherited tags with the specified key at the workspace level. |
Sample payload
{ "data": { "id": "rtk-Tj86UdGahKGDiYXY", "type": "reserved-tag-keys", "attributes": { "key": "env", "disable-overrides": true, "created-at": "2024-09-04T05:02:06.794Z", "updated-at": "2024-09-04T05:02:06.794Z" } }}
Sample request
$ curl \ --header "Authorization: Bearer $TOKEN" \ --header "Content-Type: application/vnd.api+json" \ --request PATCH \ https://app.terraform.io/api/v2/reserved-tags/${RESERVED_TAG_ID}
Sample response
{ "data": { "id": "rtk-zMtWLDftAjY3b5pA", "type": "reserved-tag-keys", "attributes": { "key": "env", "disable-overrides": true, "created-at": "2024-09-04T05:05:10.449Z", "updated-at": "2024-09-04T05:05:13.486Z" } }}
Delete a reserved tag key
DELETE /reserved-tags/:reserved_tag_key_id
Sample payload
This endpoint does not require a payload.
Sample request
$ curl \ --header "Authorization: Bearer $TOKEN" \ --header "Content-Type: application/vnd.api+json" \ --request DELETE \ https://app.terraform.io/api/v2/reserved-tags/rtk-zMtWLDftAjY3b5pA
Sample response
This endpoint does not return a response body.