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 occur only one time on a resource.
- keys that start with
verdictan:are reserved.
Verdictan normalizes the tag sequence. Do not use the sequence to encode meaning. Each ASCII character uses one byte. A non-ASCII character can use more than one byte. Validate the encoded byte length when integrations accept internationalized tag values.
Where tags are shown
The console gives tag management on supported resource detail pages. These resources include agents, gateways, configurations, provider keys, tokens, teams, roles, policies, and members. Some History sessions and Trail events also support tags.
Use the entity's Tags tab or Manage tags action. The management URL must contain a resource type and a resource ID. The owning detail page usually contains this URL.
Availability on one resource type does not imply that each API object is taggable.
Manual and declarative ownership
Each 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 config to prevent 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.
- Make sure that the keys are not duplicate or reserved.
- Save.
- Verify grouping, attribution, or policy behavior in the owning surface.
- Review Trail for the mutation.
Bulk edit accepts one key=value pair on each line. Reserved tags stay
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 | Alternative method for the same replacement operation |
DELETE | /v1/resources/{resource_type}/{resource_id}/tags/{key} | Remove one user-managed key |
Use PUT and PATCH as replacement operations. Get the active state.
Merge the necessary changes. Send the complete user-managed set. Use the
standard error envelope and request ID in
API Basics.
Define 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. Do not use 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 uses a tag:
- Make sure that the resource has the tag.
- Make sure that an unauthorized principal cannot change the tag source.
- Test the matching and non-matching cases.
- Define behavior for a missing tag.
- Review Trail after changes.
A UI filter is not an authorization boundary. The API is the enforcement point.
Attribution checks
When billing or usage is shown in Unattributed:
- Make sure that the request resolved to the correct agent, gateway, user, and team.
- Make sure that the tags were on the resources at request time.
- Examine spelling and controlled values.
- Make sure that the usage view groups by the selected tag dimension.
- Preserve the time window before correcting future attribution.
A tag update can correct subsequent attribution. It does not necessarily change historical billing records.