Skip to content

How to Manage Users

User management with UserManagementAPI and the org-search scripts.

Required token

All user management operations require SYNC_TOKEN configured in your environment. See Authentication for details.

List and Find Users

from silo_sdk import UserManagementAPI, load_config

config = load_config()
users = UserManagementAPI(config)

# List all users in an org
user_list = users.list_users("my_org")
print(f"Found {len(user_list)} users")

# Get a specific user
user = users.get_user("jane.smith@company.com")
print(f"Status: {user.get('status')}")
print(f"Org: {user.get('org')}")

User Lifecycle

# Add a new user
result = users.add_user(
    org="my_org",
    username="new.user@company.com",
    email="new.user@company.com",
    given_name="New",
    surname="User",
    phone="+18885550100",
)
print(f"Created: {result.get('username')}")

# Modify user details
users.modify_user(
    username="new.user@company.com",
    given_name="Updated",
    surname="Name",
)

# Suspend (disable without deleting)
users.suspend_user("problem.user@company.com")

# Re-enable
users.unsuspend_user("problem.user@company.com")

# Reset PIN (returns temporary password)
reset_info = users.reset_pin("user@company.com")
print(f"Temp password: {reset_info.get('temporary_password')}")

# Permanently delete
users.delete_user("departed.user@company.com")

Unlock a Locked-Out User

A lockout is not a suspension. Suspension is something an administrator does; a lockout is the platform's own response to failed authentication. They are cleared by different calls, so check which one you are looking at before acting:

user = users.get_user("locked.user@company.com")

if user.get("is_locked") or user.get("oob_locked"):
    users.unlock_user(user["username"])
elif user.get("is_suspended"):
    users.unsuspend_user(user["username"])

Two locks exist and an account can be under both at once:

Field Set by Clears on its own?
is_locked / failed_login_attempts Failed PIN or temporary-password attempts No — stays until cleared
oob_locked / oob_lock_expires_at Failed SMS or voice verification codes Yes, at oob_lock_expires_at

unlock_user() clears both, so a single call is enough regardless of which one tripped. Checking only is_locked will report a user who is locked out by the out-of-band counter as unlocked.

You cannot unlock yourself

The platform rejects an unlock whose target is the account behind the token making the request. The same restriction applies to suspend_user() and unsuspend_user(). Use a second administrator account.

Find Users Across an Org Tree

Use scripts/find_user_orgs.py to search a top-level org and all its descendants:

export A8_TOP_ORG="my_company"
export A8_SYNC_TOKEN="your-sync-token"

# Search for all users and which sub-org they belong to
python scripts/find_user_orgs.py

# Results show: username → org_slug mapping across the entire tree

Move Users Between Orgs

export A8_TOP_ORG="my_company"
export A8_TARGET_ORG="destination_sub_org"

# Dry run first (default) — shows what would be moved
python scripts/move_users.py

# Actually move
python scripts/move_users.py --execute

# Move specific users from a file
python scripts/move_users.py --users-file scripts/input_files/usernames.txt --execute

usernames.txt format: one username per line.

Organization Context

Some user operations require knowing which org a user belongs to. Use OrgManagementAPI to traverse the hierarchy:

from silo_sdk import OrgManagementAPI

orgs = OrgManagementAPI(config)

# Get all direct children of an org
children = orgs.get_org_children("my_company")
for child in children:
    print(f"Sub-org: {child.get('vanity_url')}")

# Recursively find all users in org tree (use find_user_orgs.py for this)

Bulk Operations

For bulk user imports or exports, iterate with error handling per user:

new_users = [
    {"username": "user1@company.com", "given_name": "User", "surname": "One"},
    {"username": "user2@company.com", "given_name": "User", "surname": "Two"},
]

for u in new_users:
    try:
        users.add_user(
            org="my_org",
            username=u["username"],
            email=u["username"],
            given_name=u["given_name"],
            surname=u["surname"],
        )
        print(f"Created: {u['username']}")
    except Exception as e:
        print(f"Failed {u['username']}: {e}")