Identity & Access Management

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

POST
/scopes/{scopeId}/iam/users/{userId}/tags

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.

Authorization

bearerToken
headerAuthorizationBearer <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.

Path Parameters

scopeId*string

Opaque ownership+authorization scope resolving to tenant + subscription + project.

userId*string

Identifier of the IAM user.

Header Parameters

Idempotency-Key?string

Optional; 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.

Formatuuid

Request Body

application/json
  1. body

Key/value pair for the "Add tag" action; mirrors the shared Tag shape.

key*string

Tag key, unique per user.

Length1 <= length <= 128
value*string

Tag value.

Lengthlength <= 256

Response Body

Tag created on the user.

application/json
  1. response

Uniform key/value tag carried by every taggable resource; doubles as a Cost Explorer dimension.

key*string
Length1 <= length <= 128
value*string
Lengthlength <= 256
curl -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"}