IAM, Members, Teams, and Roles

Keeptrusts access is assembled from four resource types:

Resource	Responsibility
User	Organization membership, invitation state, and account lifecycle
Team	A group of organization members and a scope for team-level access
Role	A reusable assignment that can be granted to a user or team
IAM policy	One or more allow/deny statements attached to roles

The normal design direction is policy → role → team or user. Prefer team assignments for shared job functions and direct user assignments for well-documented exceptions.

Before changing access

Authenticate and confirm the target identity and region:

kt auth whoami
kt regions current

List the current resources:

kt iam policy list
kt role list
kt team list
kt user list

API-backed IAM commands support --profile, --region, --api-url, --api-token, and --config. Prefer a signed-in profile or KEEPTRUSTS_API_TOKEN over putting a token in shell history.

Create a least-privilege role

Create a reusable policy:

kt iam policy create \
  --name "Evidence Reader" \
  --description "Read governance events and exported evidence" \
  --effect allow \
  --action events:read \
  --action exports:read \
  --resource '*'

At least one --action and one --resource are required. Repeat either flag to build the statement. Use --conditions-json only with reviewed JSON conditions.

Create a role and attach the policy:

kt role create \
  --name "Evidence Reviewer" \
  --description "Reviews events and evidence exports"

kt role attach-policy \
  --role-id role_example \
  --policy-id policy_example

Inspect what the role grants and where it is assigned:

kt role show-actions --role-id role_example
kt role show-assignments --role-id role_example

Use the Permissions Reference for current public action names. A wildcard resource is broad; replace '*' with reviewed KRN patterns when the workflow can be scoped more narrowly.

Invite and manage members

Invite a member with an organization-level role:

kt user invite \
  --email reviewer@example.com \
  --role-id role_example \
  --assignment-level org

For a team-level invitation, provide the team as the assignment target:

kt user invite \
  --email analyst@example.com \
  --role-id role_example \
  --assignment-level team \
  --assignment-target-id team_example

Member lifecycle commands include:

kt user get --user-id user_example
kt user update --user-id user_example --name "Alex Reviewer"
kt user suspend --user-id user_example --yes
kt user reactivate --user-id user_example
kt user remove-membership --user-id user_example --yes

Suspension is the safer temporary response when access may need to be restored. Membership removal is destructive; review owned tokens, team membership, open work, billing attribution, and evidence ownership before confirming it.

Direct role assignment supports organization and team scope:

kt user assign-role \
  --user-id user_example \
  --role-id role_example \
  --assignment-level org

For --assignment-level team, add --assignment-target-id team_example. Detaching a role uses the same scope fields and requires --yes.

Create and manage teams

kt team create \
  --name "Security Review" \
  --description "Governance evidence reviewers"

kt team add-member \
  --team-id team_example \
  --email reviewer@example.com

kt team assign-role \
  --team-id team_example \
  --role-id role_example

Review effective membership:

kt team get --team-id team_example
kt team list-members --team-id team_example

Removing a member or detaching a role requires explicit confirmation:

kt team remove-member \
  --team-id team_example \
  --user-id user_example \
  --yes

kt team detach-role \
  --team-id team_example \
  --role-id role_example \
  --yes

Deleting a team does not mean the affected people lose every permission. Check direct user assignments and memberships in other teams.

Change and remove policies safely

Use get before update or delete:

kt iam policy get --policy-id policy_example --json
kt role show-assignments --role-id role_example --json

Recommended removal order:

Identify every user and team assignment.
Confirm an alternative access path where one is required.
Detach the role from users and teams.
Detach the policy from the role with kt role detach-policy ... --yes.
Delete the now-unused role or policy with its command's --yes guard.
Verify with the list, action, and assignment commands.
Review the resulting Trail records.

An access change can affect console, CLI, API, and token workflows immediately. Test with a non-owner account that represents the intended role; owner access can hide missing grants.

Command inventory

Family	Commands
Policies	`kt iam policy list/get/create/update/delete`
Roles	`kt role list/get/create/update/delete/attach-policy/detach-policy/show-actions/show-assignments`
Users	`kt user list/get/invite/update/suspend/reactivate/remove-membership/assign-role/detach-role`
Teams	`kt team list/get/create/update/delete/add-member/remove-member/assign-role/detach-role/list-members`

Use --json for commands that support machine-readable automation, and use the exit status as the success signal.

Before changing access​

Create a least-privilege role​

Invite and manage members​

Create and manage teams​

Change and remove policies safely​

Command inventory​

Next steps​