Preview — pending review
This reference is generated from the platform API contract and is still under review. Operations, fields, and descriptions can change before publication.
Add a governance tag to a user
Adds a key/value tag to the selected user (the "Add tag" action on the Tags tab). User tags are
governance metadata — alongside derived tags such as department, employee-id, account-type, mfa
and directory — and propagate to access reviews and cost-attribution reports. The created tag
becomes immediately visible on the user's Tags tab and in downstream reporting dimensions.
Validation: userId must exist and be visible in scopeId (404 via ErrNotFound); key is
required, 1–128 characters, and must be unique among the user's tags — a duplicate key returns
409 CONFLICT; value is required and at most 256 characters; malformed keys/values return
422 VALIDATION_FAILED; the caller must hold owner|admin on the scope.
Async & state: Synchronous — returns 201 with the created tag. A resource.updated SSE
frame (kind iam.user, patch on tags) is emitted so open detail views and dependent reports
refresh; propagation into access-review and cost-attribution read models happens eventually in
the background.
Errors: 401 unauthenticated; 403 when the caller lacks owner|admin on the scope; 404 when
scopeId/userId is unknown; 409 when the tag key already exists on the user; 422 on
key/value validation failure; 500 on write failure.
Idempotency/Concurrency: Idempotency-Key is optional (recommended) because the UI can
retry; replaying
the same key returns the originally created tag instead of failing on the duplicate-key
conflict it would otherwise raise.
bearerTokenAuthorizationBearer <token>An API token (pc_live_…) or a service-account key (sak_live_…), created in Identity & Access Management and sent as Authorization: Bearer <token>. Requests are rate limited per credential and per tenant: every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, and a refused request gets 429 RATE_LIMITED with Retry-After.
scopeId*stringOpaque ownership+authorization scope resolving to tenant + subscription + project.
userId*stringIdentifier of the IAM user.
Idempotency-Key?stringOptional; recommended for safe retries. When sent, the same key+body within 24h replays the original result and the same key with a different body is 409 CONFLICT; keys are unique per tenant. When an API token or service-account (bearer) caller omits it, the request is applied once with no replay protection (a retry may apply it again). A console session gets one from the edge.
uuidapplication/json- body
Key/value pair for the "Add tag" action; mirrors the shared Tag shape.
key*stringTag key, unique per user.
1 <= length <= 128value*stringTag value.
length <= 256Tag created on the user.
application/json- response
Uniform key/value tag carried by every taggable resource; doubles as a Cost Explorer dimension.
key*string1 <= length <= 128value*stringlength <= 256curl -X POST "https://example.com/scopes/string/iam/users/string/tags" \ -H "Content-Type: application/json" \ -d '{ "key": "string", "value": "string" }'{ "key": "string", "value": "string"}