Resource Tags
Resource tags are key/value metadata used for grouping, search, attribution, and policy-aware workflows. Good tags connect resource ownership to operations without putting business rules into display names.
Examples:
environment=production
cost-center=cc-1042
data-classification=restricted
service=customer-support
owner-team=trust-platform
Limits and validation
For user-managed tags:
- a resource can have at most 50 user-managed tags;
- keys must be nonempty and at most 128 UTF-8 bytes;
- values must be nonempty and at most 256 UTF-8 bytes;
- each key can appear only once on a resource; and
- keys beginning with
keeptrusts:are reserved.
Keeptrusts normalizes tag order. Do not use ordering to encode meaning. ASCII text uses one byte per character; non-ASCII characters can use more. Validate the encoded byte length when integrations accept internationalized tag values.
Where tags appear
The console exposes tag management from supported resource detail pages, including agents, gateways, configurations, provider keys, tokens, teams, roles, policies, members, History sessions, and Trail events where the resource supports tagging.
Use the entity's Tags tab or Manage tags action. The management URL requires both a resource type and resource ID and is normally reached from the owning detail page.
Availability on one resource type does not imply that every API object is taggable.
Manual and declarative ownership
Every tag set has a management source.
- Manual resources can be edited in the console or through the resource-tag API.
- Declarative-managed resources are read-only in the console; update the owning manifest or configuration to avoid drift.
When the console says tags are managed elsewhere, do not work around it with a direct API call. Change the declared source and reconcile it through its owning workflow.
Add tags in the console
- Open the resource detail page.
- Select Tags or Manage tags.
- Review the management source.
- Add or update one key/value pair at a time, or use the bulk editor.
- Check for duplicate and reserved keys.
- Save.
- Verify grouping, attribution, or policy behavior in the owning surface.
- Review Trail for the mutation.
Bulk edit accepts one key=value pair per line. Reserved tags remain
unchanged.
API operations
For integrations that are authorized to manage manual tags:
| Method | Path | Purpose |
|---|---|---|
GET | /v1/resources/{resource_type}/{resource_id}/tags | Read tags and management source |
PUT | /v1/resources/{resource_type}/{resource_id}/tags | Replace the user-managed tag set |
PATCH | /v1/resources/{resource_type}/{resource_id}/tags | Alternate method for the same replacement operation |
DELETE | /v1/resources/{resource_type}/{resource_id}/tags/{key} | Remove one user-managed key |
Treat both PUT and PATCH as replacement: fetch current state, merge
intentionally, and send the complete desired user-managed set. Use the
canonical error envelope and request ID described in
API Fundamentals.
Design a tag taxonomy
Use a small controlled vocabulary:
| Dimension | Example | Why it helps |
|---|---|---|
| Environment | environment=production | Rollout and incident filtering |
| Ownership | owner-team=trust-platform | Routing and review ownership |
| Cost | cost-center=cc-1042 | Billing attribution |
| Data | data-classification=restricted | Policy targeting and review |
| Workload | service=customer-support | Fleet and agent grouping |
| Lifecycle | lifecycle=canary | Rollout comparison |
Document allowed keys, values, owners, and deprecation rules. Avoid free-form
synonyms such as prod, production, and prd.
Security guidance
Tags are metadata, not a secret store. Do not put credentials, personal data, customer prompts, incident details, or payment information in keys or values.
If a policy or route depends on a tag:
- Confirm the resource is actually tagged.
- Confirm the tag source cannot be changed by an unauthorized principal.
- Test the matching and non-matching cases.
- Define behavior for a missing tag.
- Review Trail after changes.
Do not treat a UI filter as an authorization boundary. The API remains the enforcement point.
Attribution checks
When billing or usage appears under Unattributed:
- Confirm the request resolved to the expected agent, gateway, user, and team.
- Confirm tags existed at request time.
- Check spelling and controlled values.
- Confirm the usage view groups by the intended tag dimension.
- Preserve the time window before correcting future attribution.
Updating a tag can improve subsequent attribution; it does not necessarily rewrite historical billing records.