A comprehensive Python wrapper for the Identory browser automation platform. This library provides a simple and intuitive interface for interacting with Identory's API endpoints, including profile management, settings configuration, tools, status management, groups, and presets.
- Complete API Coverage - Full support for all Identory API endpoints
- Playwright Compatibility - Works perfectly with Playwright CDP.
- Type Safety - Comprehensive type hints for better IDE support
- Error Handling - Custom exceptions with detailed error messages
- Auto-Launch - Automatically starts the Identory CLI service
- Cross-Platform - Works on Windows, macOS, and Linux
- Easy to Use - Simple, intuitive API design
- Well Documented - Extensive documentation and examples
pip install identorygit clone https://github.com/okoyausman/identory-python-wrapper.git
cd identory-python-wrapper
pip install -e .from identory import IdentoryWrapper
# Initialize the client (this will auto-launch Identory CLI)
client = IdentoryWrapper(access_token="your-access-token", auto_launch=True)
# Get all profiles
profiles = client.get_profiles()
print(f"Found {len(profiles)} profiles")
# Create a new profile
profile = client.create_profile("My Browser Profile")
print(f"Created profile: {profile['name']}")
# Start a profile
result = client.start_profile(profile['id'], headless=False)
print(f"Profile started with WebSocket: {result['browserWSEndpoint']}")
# Connect with Playwright-python (optional)
import asyncio
from playwright.async_api import async_playwright
async def quick_automation():
playwright = await async_playwright().start()
browser = await playwright.chromium.connect_over_cdp(result['browserWSEndpoint'])
context = browser.contexts[0] if browser.contexts else await browser.new_context()
page = context.pages[0] if context.pages else await context.new_page()
await page.goto('https://example.com')
await browser.close()
client.stop_profile(profile['id'])
# Run automation
asyncio.run(quick_automation())from identory import IdentoryWrapper
client = IdentoryWrapper(
access_token="your-access-token",
auto_launch=True, #Default True to auto launch CLI, set False if you handled it in your app
base_url="http://127.0.0.1", # Default localhost
port=3005, # Default port
timeout=30 # Default timeout
)# Get all profiles
profiles = client.get_profiles()
# Get specific profile
profile = client.get_profile("profile-id")
# Create a new profile
profile = client.create_profile(
name="Test Browser",
timezone="UTC",
platform="Win32"
)
# Update a profile
updated_profile = client.update_profile(
"profile-id",
name="Updated Name",
timezone="America/New_York"
)
# Start a profile
result = client.start_profile(
"profile-id",
headless=False,
skipConnectionCheck=False,
changeIP=True
)
# Stop a profile
client.stop_profile("profile-id")
# Get running profiles
running = client.get_running_profiles()
# Get profile status
status = client.get_profile_status("profile-id")
# Change profile IP
client.change_profile_ip("profile-id")
# Import/Export profiles
client.import_profile("path/to/profile.zip", {"name": "Imported Profile"})
client.export_profile("profile-id", "path/to/export.zip")
# Cookie management
cookies = client.get_profile_cookies("profile-id")
client.export_profile_cookies("profile-id", "cookies.json")
# Profile warmup
client.start_profile_warmup(
"profile-id",
["https://www.google.com", "mountain", "https://www.youtube.com"],
skipConnectionCheck=False
)
# Human typing
client.human_typing("profile-id", "Hello, world!")
# Delete profiles
client.delete_profile("profile-id")
client.delete_profiles(["id1", "id2"])# Get default settings
settings = client.get_default_settings()
# Set default settings
client.set_default_settings(
autoStartProfiles=False,
maxConcurrentProfiles=5
)# Check proxy connection
proxy_result = client.check_proxy(
"proxy.example.com",
8080,
"http://",
"username",
"password"
)
# Get IP information
ip_info = client.get_ip_info(
"proxy.example.com",
8080,
"socks5://",
"username",
"password"
)# Get all statuses
statuses = client.get_statuses()
# Create a status
status = client.create_status("In Progress", "primary")
# Update a status
client.update_status("status-id", name="Completed", color="success")
# Delete a status
client.delete_status("status-id")# Get all groups
groups = client.get_groups()
# Create a group
group = client.create_group("Work Group", "blue")
# Update a group
client.update_group("group-id", name="Updated Group", color="green")
# Delete a group
client.delete_group("group-id")# Get all presets
presets = client.get_presets()
# Create a preset with proxy
preset = client.create_preset(
"Proxy Preset",
useProxy=2,
proxyType="socks5://",
proxyHost="127.0.0.1",
proxyPort="5000",
proxyUsername="user",
proxyPassword="pass"
)
# Create a preset with screen size
preset = client.create_preset(
"Desktop Preset",
screenSize="1920x1080",
platform="Win32",
platformVersionLimit=2
)
# Update a preset
client.update_preset("preset-id", proxyHost="new.proxy.com")
# Delete a preset
client.delete_preset("preset-id")You need a valid Identory access token to use this wrapper. You can obtain one from your Identory dashboard.
The wrapper automatically attempts to launch the Identory CLI service when initialized. It supports:
- Windows:
%userprofile%\AppData\Local\Programs\identory\identory.exe - macOS:
/Applications/IDENTORY.app/Contents/MacOS/IDENTORY - Linux:
identory(must be in PATH)
The Identory wrapper works seamlessly with Playwright for browser automation. Here's how to connect Playwright to an Identory profile:
import asyncio
from identory import IdentoryWrapper
from playwright.async_api import async_playwright
async def browser_automation():
# Initialize Identory client
client = IdentoryWrapper()
# Start a profile
start_response = client.start_profile(
"your-profile-id",
headless=False
)
# Connect Playwright to the profile
playwright = await async_playwright().start()
browser = await playwright.chromium.connect_over_cdp(result['browserWSEndpoint'])
# Get a new page
context = browser.contexts[0] if browser.contexts else await browser.new_context()
page = context.pages[0] if context.pages else await context.new_page()
# Navigate to a website
await page.goto('https://example.com', timeout=30000)
# Perform actions
await page.keyboard.type('input[name="username"]', 'random-username')
await page.keyboard.type('input[name="passwd"]', 'random-password')
await page.click('button[type="submit"]')
# Take a screenshot
await page.screenshot(path='webpage.png')
# Close browser
await browser.close()
# Stop the profile
client.stop_profile("your-profile-id")
# Run the automation
asyncio.run(browser_automation())from identory import IdentoryWrapper, APIError, AuthenticationError, NotFoundError
try:
profile = client.get_profile("invalid-id")
except NotFoundError:
print("Profile not found")
except AuthenticationError:
print("Invalid access token")
except APIError as e:
print(f"API Error: {e}")# Create a profile from a preset
preset = client.get_preset("preset-id")
profile = client.create_profile(
name="Profile from Preset",
**preset # Apply preset settings
)
# Bulk operations
profile_ids = ["id1", "id2", "id3"]
client.delete_profiles(profile_ids)# Create preset with custom screen size
preset = client.create_preset(
"Custom Screen",
hasCustomScreenSize=True,
customScreenWidth=1366,
customScreenHeight=768
)# Create mobile preset
mobile_preset = client.create_preset(
"Mobile Safari",
platform="iPhone",
mobileBrowser="SAFARI"
)-
Identory CLI not found
Solution: Ensure Identory is properly installed and accessible -
Connection refused
Solution: Check if the port is available and Identory is running -
Authentication failed
Solution: Verify your access token is valid and not expired -
Profile not found
Solution: Ensure the profile ID exists and you have access to it
- Python 3.8+
- Identory application installed
- Valid Identory access token
For browser automation with Playwright:
pip install playwright
playwright installContributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
- Documentation: https://docs.identory.com
- Issues: GitHub Issues
- Email: usmanokoya10@gmail.com
Made with ❤️ for the Identory community