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

workspace create --name <name>

Create a workspace; for asynchronous creation workflows, use workspace start-creation --name <name> and workspace creations.

workspace update --workspace-id <id> --name <name>

Rename an existing workspace.

workspace claim --workspace-id <id> / workspace delete --workspace-id <id>

Claim a workspace, or delete a workspace after verifying downstream resources.

workspace ensure --name <name>

Match an accessible workspace by exact name, or create a new workspace if none matches.

workspace-member invite --email <email> --role-ids <ids> [--default-role-id <id>]

Invite a member to the workspace with initial bound roles.

workspace-member update-status --user-id <uid> --action <action> / delete --user-id <uid>

Change member status or remove a member from the workspace.

workspace-member user-tags / create-user-tag --name <name> / update-user-tag --tag-id <id> --name <name> / delete-user-tag --tag-id <id>

List, create, rename, or delete workspace user tags.

workspace-member audit-logs [--start-time <ts>] [--end-time <ts>] [--page <n>] / audit-log-overview

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

iam permission-schema / iam roles / iam role-permission-view --role-id <id>

Inspect the workspace permission catalog, role list, and a role’s permissions and concurrency versions.

iam user-role-bindings --user-id <uid>

Read a member’s bound roles, default role, and current binding version.

iam put-user-role-bindings --user-id <uid> [--use-current-versions] --json-file <path>

Replace a member’s complete role binding set and default role.

iam create-role --json-file <path> / iam update-role --role-id <id> --json-file <path>

Create a custom role, or replace a role’s policy definition.

iam update-role-lifecycle --role-id <id> --json-file <path>

Update a role’s active/disabled lifecycle state.

iam validate-object-grants --resource-type <type> --resource-id <id> --role-id <rid> --json-file <path>

Dry-run validate object grant mutations without persisting changes.

iam apply-object-grants --resource-type <type> --resource-id <id> --role-id <rid> --json-file <path>

Apply object grant mutations, then verify with iam object-permission-view.

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-role requires a unique request_id and at least one valid initial permission.

  • iam update-role takes a full replacement payload containing the role name, permission_schema_version, expected concurrency versions for the role, application policy, and data privileges (read from role-permission-view), and the complete set of application policies to retain.

  • Verify role_id, updated version counters, provisioning_state=ready, and session_invalidation_status in 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, and effective_role_id, effective_role_db_role, and effective_role_version.

  • On every newly opened database connection (including each connection created by a connection pool), execute every statement in session_init_sqls sequentially on that same connection before running business SQL; close the connection immediately if any initialization statement fails. moi-cli only fetches metadata and does not connect to the database.

  • Re-run account db-connection for 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-logs and audit-log-overview report completed events only and cannot revert role, member, or permission changes.

  • In 0.1.0 offline packages, iam role-members returns only the default member page without --cursor or --limit flags; always re-run iam role-delete-impact after updating bindings to verify remaining blockers.

  • When iam update-role, iam delete-role, or iam apply-data-privileges encounters a timeout or unknown outcome, inspect the existing receipt with the original request_id before submitting a new write request.

Last updated on