kt role

The kt role command group manages IAM roles for the Keeptrusts platform. Roles do not carry standalone permissions. Instead, they act as reusable attachment containers for one or more IAM policies.

Users, teams, and API tokens receive access by holding roles. The effective decision is then computed from the attached policy set at evaluation time.

Use this page when

• You need to create, update, or delete IAM roles from the CLI.
• You want to attach or detach IAM policies to/from roles.
• You need to inspect effective permissions or see which users, teams, and tokens hold a role.

Primary audience

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

CRUD Operations

List roles

kt role list

Get a role

kt role get --role-id role_abc123

Create a role

kt role create --name "Policy Admin" --description "Can manage policy configurations"

Update a role

kt role update --role-id role_abc123 --name "Senior Policy Admin"

Delete a role

kt role delete --role-id role_abc123 --yes

Policy Attachment

Roles gain their effective permissions through attached IAM policies. A role without attached policies grants nothing.

Attach a policy to a role

kt role attach-policy --role-id role_abc123 --policy-id policy_xyz

Detach a policy from a role

kt role detach-policy --role-id role_abc123 --policy-id policy_xyz

Inspection

Show permitted actions

View the resolved allow, deny, and resource surface of a role:

kt role show-actions --role-id role_abc123

Show role assignments

View where a role is currently assigned (users, teams, and tokens):

kt role show-assignments --role-id role_abc123

Role Model

• Roles are reusable containers for attached policies.
• Policies stay versioned independently from the role.
• Teams are the normal way to share a role across many members.
• Direct user assignments are best reserved for exceptions or temporary elevation.

Typical Workflow

# Create a role for a shared job function
kt role create --name "Gateway Operator" --description "Operate and inspect gateways"

# Attach one or more policies
kt role attach-policy --role-id role_abc123 --policy-id policy_ops
kt role attach-policy --role-id role_abc123 --policy-id policy_events

# Assign the role to a team
kt team assign-role --team-id team_platform --role-id role_abc123

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

# Review current holders of the role
kt role show-assignments --role-id role_abc123

For AI systems

• Canonical command: kt role with subcommands list, get, create, update, delete, attach-policy, detach-policy, show-actions, show-assignments.
• Flags: --role-id, --name, --description, --policy-id.
• Roles gain permissions through attached IAM policies and have no standalone action grants.
• show-actions expands the current effective action and resource surface, including allow and deny results.
• show-assignments enumerates users, teams, and API tokens attached to the role.
• Related pages: kt iam policy, kt user, kt team, Members, Teams, and Roles.

For engineers

• Prerequisites: an authenticated session with roles:write for create, update, delete, and policy attachment; roles:read for inspection.
• Validate: after kt role create, confirm with kt role get --role-id <id>. After attaching or detaching a policy, rerun kt role show-actions --role-id <id>.
• Prefer team assignments for stable job-function access. Use direct user attachments when the grant is intentionally exceptional.
• Treat show-actions as the source of truth for what a role currently grants, especially after a policy version changes.
• If a privileged role mutation is rejected, review whether the attempted grant exceeds the caller's current permission boundary.

For leaders

• Roles are the assignment layer, not the permission document. That separation lets security teams revise policies without remapping every user.
• Keep roles narrow and job-focused, such as "Escalation Reviewer" or "Configuration Publisher".
• Periodic kt role show-assignments reviews give a quick view of which users, teams, and tokens still hold a sensitive role.
• Permission boundaries cap what privileged operators can delegate, which reduces the risk of accidental privilege escalation.

Next steps

• kt iam policy — Manage the policies attached to roles
• kt user — Assign roles to users
• kt team — Assign roles to teams
• CLI Command Groups
• Members, Teams, and Roles