`huudis.iam.policy_attached.v1`

Fires when an IAM policy is attached to a principal (user, group, role, or service account).

Subscribe if you want a real-time stream of IAM changes for compliance feeds, security analytics, or a "change of access" audit pipeline that needs to react faster than nightly audit-log exports.

Not yet emitted in v1. Audit log carries iam.policy_attached entries.

When it fires

When POST /v1/iam/policy-attachments succeeds. One event per new attachment row. Re-attaching the same (policy, principal) returns 409 ALREADY_ATTACHED and does not fire.

Payload

{
  "id": "evt_01KPG…",
  "type": "huudis.iam.policy_attached.v1",
  "createdAt": "2026-05-12T23:55:00.000Z",
  "data": {
    "attachmentId": "pat_01KPG…",
    "policyId": "pol_01KPG…",
    "policyName": "HuudisReadOnly",
    "policyScope": "system",
    "principalType": "group",
    "principalId": "grp_01KPG…",
    "principalName": "Read-only Auditors",
    "accountId": "acc_01KPG40…",
    "attachedByUserId": "usr_01KPG30SP…",
    "attachedAt": "2026-05-12T23:55:00.000Z"
  }
}

principalName is a denormalised convenience — user email, group name, role name, or service-account name — so downstream consumers don't have to round-trip back to Huudis to render the alert.

Handler examples

// Node — emit to compliance pipeline
if (event.type === 'huudis.iam.policy_attached.v1') {
  const a = event.data;
  await compliance.log({
    kind: 'iam_change',
    actor: a.attachedByUserId,
    target: { type: a.principalType, id: a.principalId, name: a.principalName },
    policy: { id: a.policyId, name: a.policyName, scope: a.policyScope },
    when: a.attachedAt,
  });
}

# Python — alert on high-privilege attachments
if event["type"] == "huudis.iam.policy_attached.v1":
    a = event["data"]
    if a["policyName"] == "HuudisAdmin":
        alerts.notify(f"HuudisAdmin granted to {a['principalName']} by {a['attachedByUserId']}")

What to do

Feed a compliance / SIEM pipeline.
Alert on attachments of high-privilege policies (HuudisAdmin, custom policies that include * actions).
Trigger a re-review workflow ("this attachment needs sign-off from a second admin within 24h").

Avoid:

Trying to reconstruct effective permissions from this event alone. You'd need to merge with group memberships, role chaining, and existing attachments — call POST /v1/authz/check for the canonical answer instead.
Treating attached-and-immediately-detached as no-op. The detach is a separate event (huudis.iam.policy_detached.v1, reserved); for short-lived permission grants you should track both.

Common pitfalls

System policy spam. Attaching a system policy to many groups fires many events. Batch your downstream processing.
Race with policy edits. A policy_attached event captures the policy ID, not the document content at that moment. If the policy was edited between event creation and your handler, the live document you fetch is the new version. Use policy.version to detect this.

huudis.iam.policy_detached.v1 — reserved, not yet emitted. The detach counterpart.
huudis.iam.policy_updated.v1 — reserved, not yet emitted. Policy document mutations.

Attachments resource — the attach/detach API.
Policies — the documents being attached.
Authz — live evaluation against the assembled set.

huudis.iam.policy_attached.v1