Metadata-Version: 2.4
Name: authloop
Version: 0.1.0
Summary: Python SDK for AuthLoop — human-in-the-loop authentication for AI agents.
Project-URL: Homepage, https://authloop.ai
Project-URL: Repository, https://github.com/authloop/authloop
Project-URL: Issues, https://github.com/authloop/authloop/issues
Author-email: AuthLoop <hello@authloop.ai>
License-Expression: MIT
License-File: LICENSE
Keywords: ai-agents,authentication,authloop,browser-automation,browser-use,captcha,human-in-the-loop,otp,playwright,stagehand
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx<1.0,>=0.27
Provides-Extra: dev
Requires-Dist: openapi-python-client>=0.21; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Description-Content-Type: text/markdown

# authloop

Python SDK for [AuthLoop](https://authloop.ai) — human-in-the-loop authentication for AI agents.

When your browser agent (Playwright, Stagehand, Browser Use, OpenClaw, any CDP runtime) hits an auth wall it cannot solve — an SMS OTP, a behavioral CAPTCHA, a password prompt, a security question, an ID upload — the agent stops. AuthLoop replaces that stop with a 30-second handoff: the agent calls `to_human()`, the live tab streams to the user's phone, the user resolves the wall directly, and the agent continues. **Credentials never touch our servers.**

## Install

```bash
pip install authloop
```

## Usage

```python
from authloop import AuthLoop

authloop = AuthLoop(api_key="al_live_...")

# When your agent hits an auth wall:
session = await authloop.to_human(
    service="HDFC NetBanking",
    cdp_url="ws://localhost:9222",
    context={"wall_type": "sms_otp", "hint": "OTP sent to ****1234"},
)

# Send session.session_url to the human (Telegram, Slack, etc.)
# Wait for the human to resolve it:
result = await authloop.wait_for_resolution(session.session_id)
# result.status == "RESOLVED" → agent continues
```

## API

### `AuthLoop(api_key, base_url=None, runtime="other")`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `api_key` | `str` | yes | API key from [authloop.ai/dashboard](https://authloop.ai/dashboard/api-keys) |
| `base_url` | `str` | no | Override API base URL (default: `https://api.authloop.ai`) |
| `runtime` | `Runtime` | no | Runtime hint reported on every audit event. One of: `"playwright"`, `"stagehand"`, `"browser-use"`, `"mcp"`, `"openclaw"`, `"other"`. Default `"other"`. |

### `await authloop.to_human(...)`

Creates a session and loops the auth to a human. Returns a `ToHumanResult` with `session_id`, `session_url`, `stream_token`, `stream_url`, `expires_at`.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `service` | `str` | yes | Human-readable service name shown on the session page (e.g. `"HDFC NetBanking"`) |
| `cdp_url` | `str` | yes | CDP endpoint — HTTP or WebSocket URL |
| `ttl` | `int` | no | Session timeout in seconds (default 600) |
| `context` | `dict` | no | `{"url": ..., "wall_type": ..., "hint": ...}` |

`wall_type` is one of: `"sms_otp"`, `"email_otp"`, `"totp"`, `"password"`, `"image_captcha"`, `"behavioral_captcha"`, `"security_question"`, `"document_upload"`, `"other"`.

### `await authloop.get_session(session_id)`

Returns current session status: `PENDING`, `ACTIVE`, `RESOLVED`, `TIMEOUT`, `ERROR`, or `CANCELLED`.

### `await authloop.resolve_session(session_id)`

Marks a session as resolved.

### `await authloop.cancel_session(session_id)`

Cancels a session.

### `await authloop.wait_for_resolution(session_id, poll_interval=3.0, timeout=600.0)`

Polls until the session reaches a terminal state. Returns the final `SessionStatus`.

## Webhooks

AuthLoop fires a `session.created` webhook the moment you call `to_human()` so you can wake up 2am jobs, page on-call, or post to chat. Configure endpoints, view delivery logs, and grab the verify snippet from your **dashboard → Webhooks**.

## Get an API Key

Sign up at [authloop.ai](https://authloop.ai) — 50 free auth assists, no credit card required.

## License

MIT
