docs: add Resource Tagging product docs and changelog

Author: wevans997-dev

src/content/changelog/resource-tagging/2026-01-28-resource-tagging-private-beta.mdx

@@ -0,0 +1,23 @@
+---
+title: Resource Tagging enters private beta
+description: Enterprise customers can now attach key-value metadata to Cloudflare resources via API.
+date: 2026-01-28
+---
+
+Resource Tagging is now available in private beta for Enterprise customers. The feature enables attaching custom key-value metadata to Cloudflare resources for organization, access control, and billing attribution.
+
+### What's included
+
+- **7 supported resource types** -- `account`, `workers_script`, `workers_script_version`, `zone`, `managed_client_certificates`, `custom_hostnames`, and `access_application_policy`.
+- **Tag filtering** -- Query tagged resources with AND/OR logic, negation, and key-only matching via the `tag` query parameter.
+- **Account and zone-level endpoints** -- Full CRUD operations for both scopes.
+- **Account Owned Token (AOT) authentication** -- Tags use account-level tokens independent of individual users, ensuring automation workflows survive user lifecycle changes.
+
+### Limitations
+
+- API-only access (no Dashboard UI).
+- `PUT` replaces all tags on a resource (no partial update).
+- `DELETE` removes all tags (no single-tag delete).
+- Querying tags for an untagged resource returns `500` instead of `404`.
+
+To get started, refer to the [Resource Tagging documentation](/resource-tagging/).

src/content/changelog/resource-tagging/2026-03-25-expanded-roles-and-aot-updates.mdx

@@ -0,0 +1,21 @@
+---
+title: Expanded roles and AOT provisioning updates
+description: Workers Admin and Tag Admin roles can now manage tags. AOTs are now provisioned on behalf of customers.
+date: 2026-03-25
+---
+
+### Expanded role support
+
+Tag management is no longer limited to Super Administrators. The following roles can now create, update, and delete tags:
+
+- **Super Administrator**
+- **Workers Admin**
+- **Tag Admin**
+
+### AOT provisioning change
+
+Account Owned Tokens for tagging are now **created on behalf of customers** by the GRM team. Customers can view their tokens but cannot modify them directly. This simplifies onboarding and ensures tokens have the correct permissions from the start.
+
+### Dashboard UI in development
+
+The Stratus-based Dashboard UI for resource tagging is in active development. A staging preview is available behind the `resource-tagging-ui-experiments` gate. The Dashboard experience will complement (not replace) the existing API.

src/content/directory/resource-tagging.yaml

@@ -0,0 +1,13 @@
+id: RsTagN
+name: Resource Tagging
+
+entry:
+  title: Resource Tagging
+  url: /resource-tagging/
+  wrap: true
+  group: Core platform
+
+meta:
+  title: Cloudflare Resource Tagging docs
+  description: Attach key-value metadata to Cloudflare resources for organization, access control, and billing attribution
+  author: "@cloudflare"

src/content/docs/resource-tagging/get-started.mdx

@@ -0,0 +1,103 @@
+---
+title: Get started
+pcx_content_type: get-started
+sidebar:
+  order: 2
+description: Enable Resource Tagging for a customer account and make your first API calls.
+---
+
+This guide walks you through enabling tagging for an Enterprise account and verifying it works.
+
+## Prerequisites
+
+Before enabling Resource Tagging, ensure the account meets these requirements:
+
+- **Enterprise plan** -- Resource Tagging is only available to Enterprise customers.
+- **Super Admin access** -- At least one user with the Super Administrator, Workers Admin, or Tag Admin role. These roles can create, update, and delete tags.
+- **API familiarity** -- The feature is API-only during the private beta. Customers must be comfortable making authenticated HTTP requests.
+
+## 1. Request enablement
+
+Contact PM Wesley Evans to request tagging enablement for a customer account:
+
+- **G-Chat**: Join the "Tags for Cloudflare" space for real-time support
+- **Email**: wesley.evans@cloudflare.com
+
+Provide the following:
+
+- **Account ID** -- The customer's Cloudflare account ID, found in the Dashboard URL or via `GET /accounts`.
+- **Use case** -- A brief description of how the customer plans to use tagging (1-2 sentences).
+- **Products to be tagged** -- Which resource types the customer plans to tag initially (for example, `workers_script`, `zone`, `custom_hostnames`).
+
+Wesley will enable the feature via [gates.cloudflare.com](https://gates.cloudflare.com). Typical turnaround is 1-2 business days.
+
+## 2. Verify tagging is enabled
+
+After receiving enablement confirmation, test the API:
+
+```bash
+curl -X GET "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/tags/keys" \
+  -H "Authorization: Bearer $API_TOKEN" \
+  -H "Content-Type: application/json"
+```
+
+### Interpreting the response
+
+| Response | Meaning | Action |
+| --- | --- | --- |
+| **200 OK** with `{"success": true, "result": [...]}` | Tagging is enabled. An empty array is normal if no tags exist yet. | Proceed with onboarding. |
+| **403** mentioning "permission" or "role" | The caller lacks required permissions. This is not a gating issue. | Verify the caller has Super Admin role or the token has `#com.cloudflare.api.account.tag.list` scope. |
+| **403** mentioning "feature" or "gate" | Tagging is not enabled for this account. | Confirm the Account ID matches what was provided to Wesley. Contact the Tags for Cloudflare G-Chat space. |
+| **401 Unauthorized** | Authentication failed. | Verify the token is valid, not expired, and formatted correctly in the `Authorization: Bearer` header. |
+| Any other response | Unexpected error. | Capture the full response body and escalate to the Tags for Cloudflare G-Chat space with the Account ID, request details, and timestamp. |
+
+:::note
+Gate changes typically propagate within seconds, but may take up to 15 minutes in rare cases. If you receive a gating error immediately after enablement, wait briefly and retry.
+:::
+
+## 3. Create your first tags
+
+Set tags on a resource using `PUT`:
+
+```bash
+curl -X PUT "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/tags" \
+  -H "Authorization: Bearer $API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "resource_type": "workers_script",
+    "resource_id": "'"$RESOURCE_ID"'",
+    "tags": {
+      "environment": "production",
+      "team": "platform"
+    }
+  }'
+```
+
+Then retrieve the tags:
+
+```bash
+curl -X GET "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/tags?resource_type=workers_script&resource_id=$RESOURCE_ID" \
+  -H "Authorization: Bearer $API_TOKEN" \
+  -H "Content-Type: application/json"
+```
+
+## 4. List tagged resources
+
+Query all tagged resources in the account, optionally filtering by tag:
+
+```bash
+# All tagged resources
+curl -X GET "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/tags/resources" \
+  -H "Authorization: Bearer $API_TOKEN"
+
+# Filter: only resources with environment=production
+curl -X GET "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/tags/resources?tag=environment=production" \
+  -H "Authorization: Bearer $API_TOKEN"
+```
+
+## Next steps
+
+- Learn the full [tag filtering syntax](/resource-tagging/how-to/filter-resources/) for complex queries.
+- Understand the [GET, merge, PUT workflow](/resource-tagging/how-to/manage-tags/#add-a-single-tag) for modifying individual tags.
+- Review [supported resource types](/resource-tagging/reference/resource-types/) and their required fields.
+- Review [API limits and validation rules](/resource-tagging/reference/limits/).

src/content/docs/resource-tagging/how-to/filter-resources.mdx

@@ -0,0 +1,115 @@
+---
+title: Filter resources by tag
+pcx_content_type: how-to
+sidebar:
+  order: 2
+description: Query tagged resources using the tag filtering syntax.
+---
+
+The `GET /accounts/{account_id}/tags/resources` endpoint supports tag filtering via the `tag` query parameter. Multiple `tag` parameters combine with **AND** logic.
+
+:::caution
+Use `=` as the separator in tag filters (for example, `tag=key=value`), not `:`. The API error message references `:` but the implementation uses `=`.
+:::
+
+## Filter types
+
+### Key-only filter
+
+Match resources that have a specific tag key, regardless of value.
+
+```bash
+# All resources with an "environment" tag (any value)
+curl -X GET "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/tags/resources?tag=environment" \
+  -H "Authorization: Bearer $API_TOKEN"
+```
+
+### Key-value filter
+
+Match resources where a tag key has a specific value.
+
+```bash
+# All resources with environment=production
+curl -X GET "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/tags/resources?tag=environment=production" \
+  -H "Authorization: Bearer $API_TOKEN"
+```
+
+### Multiple values (OR)
+
+Match resources where a tag key has any of the specified values. Separate values with commas.
+
+```bash
+# environment=production OR environment=staging
+curl -X GET "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/tags/resources?tag=environment=production,staging" \
+  -H "Authorization: Bearer $API_TOKEN"
+```
+
+Maximum of 10 OR values per filter (error code `1013` if exceeded).
+
+### Negate key
+
+Match resources that do **not** have a specific tag key.
+
+```bash
+# All resources without an "archived" tag
+curl -X GET "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/tags/resources?tag=!archived" \
+  -H "Authorization: Bearer $API_TOKEN"
+```
+
+### Negate key-value
+
+Match resources where a tag key does **not** have a specific value.
+
+```bash
+# All resources where region is NOT us-west-1
+curl -X GET "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/tags/resources?tag=region!=us-west-1" \
+  -H "Authorization: Bearer $API_TOKEN"
+```
+
+## Combining filters
+
+Multiple `tag` parameters combine with AND logic. All conditions must match.
+
+```bash
+# Production resources in US regions, excluding archived
+curl -X GET "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/tags/resources?tag=environment=production&tag=region=us-west-1,us-east-1&tag=!archived" \
+  -H "Authorization: Bearer $API_TOKEN"
+```
+
+Maximum of 20 tag filters per query (error code `1010` if exceeded).
+
+## Discover available tags
+
+### List all tag keys
+
+```bash
+curl -X GET "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/tags/keys" \
+  -H "Authorization: Bearer $API_TOKEN"
+```
+
+### List values for a key
+
+```bash
+curl -X GET "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/tags/values/environment" \
+  -H "Authorization: Bearer $API_TOKEN"
+```
+
+Optionally filter by resource type:
+
+```bash
+curl -X GET "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/tags/values/environment?type=workers_script" \
+  -H "Authorization: Bearer $API_TOKEN"
+```
+
+## Pagination
+
+All list endpoints use cursor-based pagination with a fixed page size of 100 results.
+
+When the response includes a non-null `result_info.cursor`, pass it as a query parameter to get the next page:
+
+```bash
+curl -X GET "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/tags/resources?tag=environment=production&cursor=$CURSOR" \
+  -H "Authorization: Bearer $API_TOKEN"
+```
+
+When `cursor` is `null`, you have reached the last page. Pagination works seamlessly with tag filters.