Workspaces and Permissions¶
Use the workspace, workspace-member, iam, and account command groups to manage workspace lifecycles, members and user tags, role inheritance, application object grants, row and column data privileges, and database connection parameters. Complete Configuration and Authentication before running these commands.
Workspaces, members, and audit logs¶
List accessible workspaces, save your target workspace ID, and verify your active principal and member roster before writing changes:
moi-cli -auth pat -o workspace list
moi-cli config set-workspace "<workspace-id>"
moi-cli -auth pat -o workspace-member current-principal
moi-cli -auth pat -o workspace-member members --page 1 --page-size 50
Common workspace, member, tag, and audit subcommands:
Subcommand and key flags |
Description |
|---|---|
|
Create a workspace; for asynchronous creation workflows, use |
|
Rename an existing workspace. |
|
Claim a workspace, or delete a workspace after verifying downstream resources. |
|
Match an accessible workspace by exact name, or create a new workspace if none matches. |
|
Invite a member to the workspace with initial bound roles. |
|
Change member status or remove a member from the workspace. |
|
List, create, rename, or delete workspace user tags. |
|
Query historical member operation audit logs and summary statistics. |
Warning
workspace ensure --name <name> has write side effects: if no accessible workspace matches <name> exactly, it creates a new workspace immediately. When a script must connect only to an existing workspace, query workspace list to resolve a confirmed ID and pass it via config set-workspace or the global -workspace-id flag.
Roles, member bindings, and object grants¶
workspace-member manages member profiles and invitations, while iam manages role definitions, existing member role bindings, and object-level grants:
Subcommand and key flags |
Description |
|---|---|
|
Inspect the workspace permission catalog, role list, and a role’s permissions and concurrency versions. |
|
Read a member’s bound roles, default role, and current binding version. |
|
Replace a member’s complete role binding set and default role. |
|
Create a custom role, or replace a role’s policy definition. |
|
Update a role’s active/disabled lifecycle state. |
|
Dry-run validate object grant mutations without persisting changes. |
|
Apply object grant mutations, then verify with |
Replace a member’s role bindings (bindings.json):
{
"assigned_role_ids": ["12", "15"],
"default_role_id": "12",
"request_id": "bind-20261113-01"
}
moi-cli -auth pat -o iam user-role-bindings --user-id "$USER_ID"
moi-cli -auth pat -o iam put-user-role-bindings \
--user-id "$USER_ID" \
--use-current-versions \
--json-file ./bindings.json
Role creation and update payload rules (run moi-cli schema iam create-role offline to inspect wire fields):
iam create-rolerequires a uniquerequest_idand at least one valid initial permission.iam update-roletakes a full replacement payload containing the role name,permission_schema_version, expected concurrency versions for the role, application policy, and data privileges (read fromrole-permission-view), and the complete set of application policies to retain.Verify
role_id, updated version counters,provisioning_state=ready, andsession_invalidation_statusin the response. For full HTTP field and state-machine details, see Update a role.
Configure role inheritance¶
Inheritance edges point from child role to parent role (the child role inherits the parent role’s permissions). Read the current lifecycle versions of both roles from iam role-permission-view first:
moi-cli -auth pat -o iam roles --workspace-id "$WORKSPACE_ID"
moi-cli -auth pat -o iam role-permission-view --workspace-id "$WORKSPACE_ID" --role-id "$CHILD_ROLE_ID"
moi-cli -auth pat -o iam role-permission-view --workspace-id "$WORKSPACE_ID" --role-id "$PARENT_ROLE_ID"
Prepare inheritance.json with the parent role ID and current lifecycle versions:
{
"parent_role_id": "15",
"expected_child_lifecycle_version": 1,
"expected_parent_lifecycle_version": 1,
"request_id": "inh-20261113-01"
}
Apply the inheritance edge and inspect the inheritance graph:
moi-cli -auth pat -o iam add-role-inheritance \
--workspace-id "$WORKSPACE_ID" \
--role-id "$CHILD_ROLE_ID" \
--json-file ./inheritance.json
moi-cli -auth pat -o iam role-inheritance-graph \
--workspace-id "$WORKSPACE_ID" \
--role-id "$CHILD_ROLE_ID"
To remove an inheritance edge, re-read the latest lifecycle versions of both roles, update inheritance.json, and run iam remove-role-inheritance --role-id "$CHILD_ROLE_ID" --json-file ./inheritance.json.
Resolve dependencies and delete a role¶
Before deleting a role, inspect bound members, owned objects, and deletion blockers, transfer owned resources to a target role, and re-verify impact:
moi-cli -auth pat -o iam role-members --workspace-id "$WORKSPACE_ID" --role-id "$ROLE_ID"
moi-cli -auth pat -o iam role-delete-impact \
--workspace-id "$WORKSPACE_ID" \
--role-id "$ROLE_ID" \
--expected-lifecycle-version "$ROLE_VERSION"
moi-cli -auth pat -o iam role-delete-ownerships --workspace-id "$WORKSPACE_ID" --role-id "$ROLE_ID"
Use --cursor on role-delete-ownerships to paginate owned objects. To transfer ownership of a table or other resource, save transfer.json and run transfer-object-ownership:
{
"target_role_id": "15",
"expected_ownership_version": 1,
"request_id": "transfer-20261113-01"
}
moi-cli -auth pat -o iam transfer-object-ownership \
--workspace-id "$WORKSPACE_ID" \
--resource-type table \
--resource-id 1001 \
--json-file ./transfer.json
After clearing all member bindings and ownership blockers, re-run iam role-delete-impact to confirm zero remaining blockers, then submit delete.json to iam delete-role:
{
"reason_code": "retired_role",
"expected_lifecycle_version": 3,
"request_id": "del-20261113-01"
}
moi-cli -auth pat -o iam delete-role \
--workspace-id "$WORKSPACE_ID" \
--role-id "$ROLE_ID" \
--json-file ./delete.json
Deleting a role cleans up its inheritance edges automatically and removes any permissions that downstream roles inherited through it.
Validate and apply row and column data privileges¶
Database table query grants and row/column masking rules are configured separately from application object grants using a four-step workflow: read current version, validate, apply the identical payload, and inspect the operation receipt.
1. Read the current version and prepare the payload¶
moi-cli -auth pat -o iam data-privileges --role-id "$TARGET_ROLE_ID" > data-view.json
Copy data_privilege_version into expected_data_privilege_version and save data-privileges.json with a numeric table resource_id (table names are not accepted) and a unique request_id:
{
"request_id": "dp-20261113-01",
"expected_data_privilege_version": 1,
"mutations": [
{
"operation": "grant",
"action_id": "table.query",
"resource_type": "table",
"resource_id": "1001",
"privilege": "select",
"row_column": {
"mode": "set",
"draft": {
"black_column_list": ["salary"],
"rule_list": [
{
"column": "region",
"relation": "and",
"expression_list": [
{
"operator": "not in",
"expression": ["blocked", "unknown"]
}
]
}
]
}
}
}
]
}
Every table.query grant must specify row_column.mode as keep, set, or clear. For multi-value in and not in operators, place all values inside a single expression array.
2. Validate, apply, and inspect the receipt¶
# 1) Validate without mutating database privileges; check valid, errors, warnings, and canonical_mutations
moi-cli -auth pat -o iam validate-data-privileges \
--role-id "$TARGET_ROLE_ID" \
--json-file ./data-privileges.json > validation.json
# 2) Apply the exact same file (preserving request_id and version)
moi-cli -auth pat -o iam apply-data-privileges \
--role-id "$TARGET_ROLE_ID" \
--json-file ./data-privileges.json > operation.json
# 3) Inspect the operation receipt by request_id
moi-cli -auth pat -o iam data-privilege-operation \
--role-id "$TARGET_ROLE_ID" \
--request-id "dp-20261113-01"
Exit code 0 indicates only that the receipt was returned; always verify the receipt state, per-resource outcomes, and session_invalidation_status, then re-read iam data-privileges.
3. Synchronize current database privilege facts¶
When a prior operation partially applied at the database layer and you need to synchronize actual database facts back into the IAM projection, read the latest data_privilege_version and prepare repair.json:
{
"request_id": "repair-20261113-01",
"expected_data_privilege_version": 2
}
Pass <original-request-id>:repair to --repair-operation (for example dp-20261113-01:repair; operation_id from the receipt is not accepted here):
moi-cli -auth pat -o iam repair-data-privileges \
--role-id "$TARGET_ROLE_ID" \
--repair-operation "dp-20261113-01:repair" \
--json-file ./repair.json
Repair reads current database facts into the projection without replaying original grant or revoke mutations; check per-resource statuses and session invalidation rules in the response.
Retrieve database connection info¶
To connect an external SQL driver or client directly to the current workspace database, run:
moi-cli -auth pat -o account db-connection
Connection and session initialization requirements:
The JSON output contains the host/port address, credentials,
session_init_sqls, andeffective_role_id,effective_role_db_role, andeffective_role_version.On every newly opened database connection (including each connection created by a connection pool), execute every statement in
session_init_sqlssequentially on that same connection before running business SQL; close the connection immediately if any initialization statement fails.moi-clionly fetches metadata and does not connect to the database.Re-run
account db-connectionfor new logical requests when role bindings or user tags change, as existing open connections do not refresh role context automatically.Treat the output as sensitive credential material and never persist it in shell history, shared CI logs, or source repositories.
Limitations and notes¶
workspace-member audit-logsandaudit-log-overviewreport completed events only and cannot revert role, member, or permission changes.In
0.1.0offline packages,iam role-membersreturns only the default member page without--cursoror--limitflags; always re-runiam role-delete-impactafter updating bindings to verify remaining blockers.When
iam update-role,iam delete-role, oriam apply-data-privilegesencounters a timeout or unknown outcome, inspect the existing receipt with the originalrequest_idbefore submitting a new write request.