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.

Replace the tag set on a service account

PUT
/scopes/{scopeId}/iam/service-accounts/{serviceAccountId}/tags

Replaces the full key/value tag set of the service account from the editable Tags tab on the detail view (e.g. env=prod, team=platform, managed-by=alican). The UI supports adding, removing and saving tags as one atomic save, so this is a full PUT replacement: tags omitted from the request are removed. The updated tag set is immediately visible to subsequent reads of the detail view. Validation: account must exist and be visible in the scope (else 404 NOT_FOUND); each tag needs a non-empty key unique within the set, and key/value must respect the platform tag length/charset limits — violations → 422 VALIDATION_FAILED; caller must hold a write-capable role (owner|admin|contributor) else 403 FORBIDDEN. Async & state: Synchronous mutation — 200 with the persisted tag set; no transitional states. Emits one resource.updated SSE frame (kind: iam.service_account, patch: {tags}) so other open sessions refresh. Errors: 401 unauthenticated; 403 lacks write permission; 404 unknown account; 422 malformed tag keys/values or duplicate keys; 500 persistence failure. Idempotency/Concurrency: Idempotency-Key recommended — replay returns the already-applied result. This operation does not check If-Match; a sent one is ignored and the last write wins.

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.

serviceAccountId*string

Service account identifier.

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

Full-replacement tag set from the editable Tags tab.

tags*array<>
Itemsitems <= 50

Response Body

Tag set replaced; returns the persisted tags.

application/json
  1. response
tags*array<>
curl -X PUT "https://example.com/scopes/string/iam/service-accounts/string/tags" \  -H "Content-Type: application/json" \  -d '{    "tags": [      {        "key": "string",        "value": "string"      }    ]  }'
{  "tags": [    {      "key": "string",      "value": "string"    }  ]}