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}")