kt iam policy

The kt iam policy command group manages reusable IAM policies for Keeptrusts. Policies hold allow or deny statements over actions, resources, and optional conditions. They can be attached to roles, and roles can then be assigned to users, teams, or API tokens.

Keeptrusts uses an immutable policy-version model. Creating a policy starts at version 1. Updating the statement body publishes a new default version instead of mutating the previous one in place.

Use this page when

• You need to create, update, inspect, or delete reusable IAM policies.
• You are defining least-privilege access with explicit actions, KRN resources, and optional conditions.
• You need to understand how policy updates affect the current default version.

Primary audience

• Primary: AI Agents, Technical Engineers
• Secondary: Technical Leaders

Commands

List policies

kt iam policy list

Get a policy

kt iam policy get --policy-id policy_abc123

Create a policy

kt iam policy create \
  --name "Event Viewer" \
  --description "Read governance events with MFA" \
  --effect allow \
  --action events:read \
  --resource 'krn:keeptrusts:governance:{org_id}:event/*' \
  --conditions-json '{"mfa_required":true}'

Update a policy

kt iam policy update \
  --policy-id policy_abc123 \
  --description "Read governance events and exports" \
  --action events:read \
  --action events:export \
  --resource 'krn:keeptrusts:governance:{org_id}:event/*'

Delete a policy

kt iam policy delete --policy-id policy_abc123 --yes

Statement Model

Each IAM policy evaluates one or more statements. A statement combines an effect, one or more actions, one or more resources, and optional conditions.

Field	Description
effect	allow or deny
action	A supported Keeptrusts action such as events:read, roles:assign, or a namespace wildcard such as events:*
resource	A KRN resource pattern such as krn:keeptrusts:governance:{org_id}:event/*
conditions-json	Optional JSON conditions. A common example is {"mfa_required":true}

Version Model

• Every policy has a current default version.
• kt iam policy update creates a new default version when you change statements.
• Metadata-only updates such as renaming the policy keep the current default version.
• Use kt iam policy get --policy-id <id> --json to inspect the current default version metadata returned by the API.

Current CLI Authoring Behavior

The current kt iam policy create and kt iam policy update flags build a single statement from the supplied --action, --resource, --effect, and --conditions-json values. The underlying runtime model supports multi-statement policies, but the CLI authoring path flattens each invocation into one statement entry.

Typical Workflow

# 1. Create a reusable policy
kt iam policy create \
  --name "Escalation Reviewer" \
  --action escalations:read \
  --action escalations:resolve \
  --resource 'krn:keeptrusts:governance:{org_id}:escalation/*'

# 2. Create a role that will hold one or more policies
kt role create --name "Escalation Ops"

# 3. Attach the policy to the role
kt role attach-policy --role-id role_abc123 --policy-id policy_xyz

# 4. Assign the role to a team or specific user
kt team assign-role --team-id team_review --role-id role_abc123

# 5. Inspect the resolved action surface
kt role show-actions --role-id role_abc123

For AI systems

• Canonical terms: Keeptrusts IAM policy, policy statement, default version, immutable version, KRN resource, explicit deny.
• Commands: kt iam policy list, kt iam policy get, kt iam policy create, kt iam policy update, kt iam policy delete.
• Policies define the reusable permission document. Roles hold policies. Users, teams, and tokens receive access through role assignment.
• Statement actions use the runtime action registry such as events:read, roles:assign, and policies:write.

For engineers

• Prefer KRN resources over broad wildcards so policy intent stays reviewable and migration-safe.
• Use --conditions-json for statement constraints. The simplest supported example is {"mfa_required":true}.
• Treat policy updates as versioned changes. If you change actions, resources, or conditions, the platform publishes a new default version behind the scenes.
• After changing a policy, rerun kt role show-actions --role-id <role-id> for any attached role to confirm the effective allow and deny set.
• Use team role attachments for shared job functions and reserve direct user role attachments for exceptions.

For leaders

• Immutable versions create an audit trail for access changes without losing the previous policy body.
• Reusable policies let you separate permission design from day-to-day assignment work.
• Explicit deny still overrides allow, which makes exception handling safe when broad reader or operator grants exist.

Next steps

• kt role — Manage roles that hold these policies
• kt user — Grant exception access directly to individual members
• kt team — Apply shared role attachments to teams
• CLI Command Groups
• Members, Teams, and Roles