Tag Policy

View as Markdown

Get a tag policyGET /api/2.1/tag-policies/{tag_key}List tag policiesGET /api/2.1/tag-policiesCreate a new tag policyPOST /api/2.1/tag-policiesUpdate an existing tag policyPATCH /api/2.1/tag-policies/{tag_key}Delete a tag policyDELETE /api/2.1/tag-policies/{tag_key}

TagPolicy object

tag_keystring[ 1 .. 256 ] charactersImmutable

Example: sensitivity_level

idstringOutput only

descriptionstring<= 4096 characters

Example: Identifies the sensitivity level of the data for compliance purposes.

valuesarray of object<= 500 itemsUnordered list

Show child attributesHide child attributes

namestring[ 1 .. 256 ] characters

create_timestringOutput only

Timestamp when the tag policy was created

update_timestringOutput only

Timestamp when the tag policy was last updated

View as Markdown

The TagPolicy object

{
  "tag_key": "sensitivity_level",
  "id": "string",
  "description": "Identifies the sensitivity level of the data for compliance purposes.",
  "values": [
    {
      "name": "public"
    },
    {
      "name": "confidential"
    }
  ],
  "create_time": "string",
  "update_time": "string"
}

Get a tag policy GA

GET /api/2.1/tag-policies/{tag_key}

Gets a single tag policy by its associated governed tag's key. For Terraform usage, see the Tag Policy Terraform documentation. To list granted permissions for tag policies, use the Account Access Control Proxy API.

API scopes: tags

Parameters

tag_keystringRequiredpath

Response

Returns the TagPolicy object.

View as Markdown

Response

{
  "create_time": "2025-01-01T10:00:00Z",
  "description": "Identifies the sensitivity level of the data for compliance purposes.",
  "id": "12345678-abcd-4ef5-9012-3456789abcde",
  "tag_key": "sensitivity_level",
  "update_time": "2025-01-01T10:00:00Z",
  "values": [
    {
      "name": "public"
    },
    {
      "name": "internal"
    },
    {
      "name": "confidential"
    },
    {
      "name": "restricted"
    }
  ]
}

List tag policies GA

GET /api/2.1/tag-policies

Lists the tag policies for all governed tags in the account. For Terraform usage, see the Tag Policy Terraform documentation. To list granted permissions for tag policies, use the Account Access Control Proxy API.

API scopes: tags

Parameters

page_sizeint32query

The maximum number of results to return in this request. Fewer results may be returned than requested. If unspecified or set to 0, this defaults to 1000. The maximum value is 1000; values above 1000 will be coerced down to 1000.

page_tokenstringquery

An optional page token received from a previous list tag policies call.

Response

Returns a list of TagPolicy objects.

View as Markdown

Response

{
  "next_page_token": "eyJwYWdlX251bWJlciI6Mn0=",
  "tag_policies": [
    {
      "create_time": "2025-01-01T10:00:00Z",
      "description": "Identifies the sensitivity level of the data for compliance purposes.",
      "id": "12345678-abcd-4ef5-9012-3456789abcde",
      "tag_key": "sensitivity_level",
      "update_time": "2025-01-01T10:00:00Z",
      "values": [
        {
          "name": "public"
        },
        {
          "name": "internal"
        },
        {
          "name": "confidential"
        },
        {
          "name": "restricted"
        }
      ]
    },
    {
      "create_time": "2025-01-01T09:30:00Z",
      "description": "Specifies data retention policy requirements.",
      "id": "abcdef12-3456-7890-abcd-ef1234567890",
      "tag_key": "data_retention",
      "update_time": "2025-01-01T09:45:15Z",
      "values": [
        {
          "name": "30_days"
        },
        {
          "name": "1_year"
        },
        {
          "name": "7_years"
        },
        {
          "name": "indefinite"
        }
      ]
    }
  ]
}

Create a new tag policy GA

POST /api/2.1/tag-policies

Creates a new tag policy, making the associated tag key governed. For Terraform usage, see the Tag Policy Terraform documentation. To manage permissions for tag policies, use the Account Access Control Proxy API.

API scopes: tags

Request body

tag_keystring[ 1 .. 256 ] charactersRequiredImmutable

Example: sensitivity_level

descriptionstring<= 4096 characters

Example: Identifies the sensitivity level of the data for compliance purposes.

valuesarray of object<= 500 itemsUnordered list

Show child attributesHide child attributes

namestring[ 1 .. 256 ] charactersRequired

Response

Returns the TagPolicy object.

View as Markdown

Request

{
  "description": "Identifies the sensitivity level of the data for compliance purposes.",
  "tag_key": "sensitivity_level",
  "values": [
    {
      "name": "public"
    },
    {
      "name": "internal"
    },
    {
      "name": "confidential"
    },
    {
      "name": "restricted"
    }
  ]
}

Response

{
  "create_time": "2025-01-01T10:00:00Z",
  "description": "Identifies the sensitivity level of the data for compliance purposes.",
  "id": "12345678-abcd-4ef5-9012-3456789abcde",
  "tag_key": "sensitivity_level",
  "update_time": "2025-01-01T10:00:00Z",
  "values": [
    {
      "name": "public"
    },
    {
      "name": "internal"
    },
    {
      "name": "confidential"
    },
    {
      "name": "restricted"
    }
  ]
}

Update an existing tag policy GA

PATCH /api/2.1/tag-policies/{tag_key}

Updates an existing tag policy for a single governed tag. For Terraform usage, see the Tag Policy Terraform documentation. To manage permissions for tag policies, use the Account Access Control Proxy API.

API scopes: tags

Parameters

tag_keystring[ 1 .. 256 ] charactersRequiredImmutablepath

Example: sensitivity_level

update_maskstringRequiredquery

Request body

descriptionstring<= 4096 characters

Example: Identifies the sensitivity level of the data for compliance purposes.

valuesarray of object<= 500 itemsUnordered list

Show child attributesHide child attributes

namestring[ 1 .. 256 ] charactersRequired

Response

Returns the TagPolicy object.

View as Markdown

Request

{
  "description": "Updated description: Identifies the sensitivity level of the data for compliance and regulatory purposes.",
  "values": [
    {
      "name": "public"
    },
    {
      "name": "internal"
    },
    {
      "name": "confidential"
    },
    {
      "name": "restricted"
    },
    {
      "name": "highly_restricted"
    }
  ]
}

Response

{
  "create_time": "2025-01-01T10:00:00Z",
  "description": "Updated description: Identifies the sensitivity level of the data for compliance and regulatory purposes.",
  "id": "12345678-abcd-4ef5-9012-3456789abcde",
  "tag_key": "sensitivity_level",
  "update_time": "2025-01-01T10:05:30Z",
  "values": [
    {
      "name": "public"
    },
    {
      "name": "internal"
    },
    {
      "name": "confidential"
    },
    {
      "name": "restricted"
    },
    {
      "name": "highly_restricted"
    }
  ]
}

Delete a tag policy GA

DELETE /api/2.1/tag-policies/{tag_key}

Deletes a tag policy by its associated governed tag's key, leaving that tag key ungoverned. For Terraform usage, see the Tag Policy Terraform documentation.

API scopes: tags

Parameters

tag_keystringRequiredpath

View as Markdown

Response

{}