Skip to main content
Use mthr iam roles to define access and mthr iam bindings to assign it. A role version is an immutable set of actions with its own role ID. A binding assigns that exact role ID to one member or service account. Members and service accounts get access only through bindings. The tenant comes from your authenticated session. Sign in as an active tenant owner to manage roles and bindings. Only owners can list, create, or disable roles, and owners can review direct and effective grants across the tenant. A custom role cannot let someone manage roles or bindings, create or deactivate service accounts, or manage service-account credentials. You can inspect built-in roles, but you cannot change or disable them. Service accounts can receive enabled custom roles from their own tenant, but not built-in roles such as Owners.

​
Find the IDs you need

List identities and role versions:
Copy member, service-account, and role IDs from the output of these commands. In the examples below, replace uppercase placeholders with those IDs. Role listing includes built-in roles and disabled custom versions. Inspect a version before granting it:
The result includes its exact actions, version number, selected action catalog, state, and built-in status. Choose an enabled version for a new binding.

​
Create a custom role

Role keys use lowercase letters, digits, and hyphens, cannot begin with a hyphen, and have a maximum length of 100 characters. A new key starts at version 1. This example creates a role with one exact action:
To include multiple actions, repeat --action:
You can also use --action directory:GetTenant,billing:ListInvoices. Action IDs are exact and case-sensitive. Wildcards, duplicate actions, unknown actions, and reserved administration actions are rejected. All requested actions must be present in one finalized action catalog. See Actions for the action IDs a custom role can include. Keep the role_id returned by the command. The CLI generates it automatically unless you pass your own unique ID with --role-id. A new role gives access only after you assign it. Mount Thor automatically selects the most recently finalized action catalog containing every requested action. If no compatible finalized catalog exists, creation fails validation.
--version numbers successive definitions of your role key. An action catalog version identifies the finalized set of action definitions used to validate that role. These are separate versions. Mount Thor stores the selected catalog on the role version and returns it as catalog_version.To reproduce a specific catalog selection, provide an explicit override. Replace CATALOG_VERSION with a finalized catalog version, such as the catalog_version that roles get shows for an existing role:
An explicit catalog must also contain every requested action. Existing role versions keep their original catalogs when newer catalogs are finalized. An idempotent API retry of the same request keeps its original selection too.
Each run of mthr iam roles create is a new request. If the command fails or times out, run roles ls and roles get to check whether the version was created before you run it again.

​
Assign a role

Grant a role version to an active member:
Or grant an enabled custom role from your tenant to an active service account:
Supply exactly one of --member-id and --service-account-id. Keep the binding ID returned by the grant, or find it later with bindings ls. You can grant a custom role with one or more actions to a service account. The grant goes through the same tenant, active-account, enabled-role, and reserved-action checks as a member grant, but it does not give the service account a credential. To issue one, see Service accounts. Role creation, role disable, binding grant, and binding revoke each require nonblank --reason and --ticket values, which read commands do not need. Use the actual reason for the change and your organization’s ticket or change reference.

​
Review assignments and effective access

Direct grants show the binding ID, subject, role ID, and state, including disabled bindings. Effective grants show the actions currently supplied by active grants, with the role and binding IDs that provide each action. Use these IDs to identify the assignment you intend to revoke. All IAM commands support --json.

​
Replace a role version

To change a role’s actions, update the role by its key:
A binding refers to one role version, so the change is a sequence, and the command runs all of it in an order that never leaves a holder without access. It creates the next version of the key and binds every member and service account that holds an older version to the new one. After a read-back check of the grants, it disables the older versions. One reason and ticket are recorded on every step. Add --dry-run to print the plan without changing anything. If a run stops part way, the output lists what landed and the exact commands that remain, and running the same command again finishes the job. The manual steps still work when you want to control each one. Create the next version with roles create KEY --version N, grant the new role ID to each subject with bindings grant, then revoke each obsolete binding. During that transition, both assignments can supply access. Mount Thor refuses to disable an older version while an active holder has not been moved to a newer one, so a subject you forgot keeps their access until you move them.

​
Revoke a binding

Use the binding ID from the direct-grants list:
This disables one assignment and keeps its history visible. Other active bindings may still grant the same action. Review the subject’s effective grants afterward to see whether another assignment provides access. Mount Thor refuses revocation of the last active owner binding.

​
Disable a role version

To retire a custom version for every subject bound to it:
Disabling removes the access supplied by that version to both members and service accounts. It does not disable other versions of the same role key or erase binding history, and other roles can still supply the same actions. mthr iam grants is an alias for mthr iam bindings, and list is an alias for ls.