# Binoauth Python SDK
A multi-tenant authentication and authorization Python SDK that supports OAuth2, OpenID Connect, API keys, and multiple authentication methods.
## Features
- **Admin API**: Management endpoints for tenants, clients, users, API keys, and provider settings
- **Tenant API**: Authentication endpoints for login, signup, OAuth2 flows, magic links, phone OTP, and user profile management
- **Multiple Authentication Methods**: API keys, Bearer tokens, session cookies
- **Auto-generated from OpenAPI**: Always up-to-date with the latest API specifications
- **Type-safe**: Full type hints and Pydantic models
- **Python 3.9+**: Modern Python support
## Installation
```bash
pip install binoauth
```
For development:
```bash
pip install -e .[dev]
```
## Quick Start
### Admin API Usage
```python
from binoauth import BinoauthAdmin
# Initialize admin client
admin = BinoauthAdmin(
host="https://api.auth.example.com",
access_token="your_admin_token"
)
# List tenants
tenants = admin.api.list_tenants_api_v1_tenants_get()
# Create a new client
client_data = {
"name": "My App",
"redirect_uris": ["https://myapp.com/callback"]
}
new_client = admin.api.create_client_api_v1_clients_post(client_data)
```
### Tenant API Usage
```python
from binoauth import BinoauthTenant
# Initialize tenant client
tenant = BinoauthTenant(
host="https://tenant.auth.example.com",
api_key="your_api_key"
)
# User signup
signup_data = {
"email": "user@example.com",
"password": "secure_password"
}
response = tenant.auth.signup_api_v1_auth_signup_post(signup_data)
# OAuth2 authorization
auth_url = tenant.oauth2.authorize_api_v1_oauth2_authorize_get(
client_id="your_client_id",
redirect_uri="https://yourapp.com/callback",
response_type="code"
)
```
### Context Manager Usage
```python
# Both classes support context managers
with BinoauthAdmin(host="...", access_token="...") as admin:
tenants = admin.api.list_tenants_api_v1_tenants_get()
with BinoauthTenant(host="...", api_key="...") as tenant:
response = tenant.auth.login_api_v1_auth_login_post(login_data)
```
## Development Setup
### Prerequisites
- Python 3.9+
- Git
- OpenAPI Generator CLI (for code generation)
### Development Installation
1. Clone the repository:
```bash
git clone <repository-url>
cd binoauth-python-sdk
```
2. Install development dependencies:
```bash
pip install -e .[dev]
```
3. Install pre-commit hooks:
```bash
pre-commit install
```
### Development Commands
#### Code Generation
```bash
# Regenerate SDK from latest OpenAPI specs
./codegen.sh
```
#### Testing
```bash
# Run all tests
python -m pytest
# Run tests with coverage
python -m pytest --cov=binoauth
# Run specific test file
python -m pytest binoauth/admin/test/test_admin_api.py
```
#### Code Quality & Linting
```bash
# Format code
black binoauth/
# Sort imports
isort binoauth/
# Lint code
flake8 binoauth/
# Type checking (manual only, auto-generated code conflicts)
mypy binoauth/__init__.py --ignore-missing-imports --allow-untyped-calls
# Run all quality checks
pre-commit run --all-files
```
#### Version Management
```bash
# Bump patch version (1.0.0 → 1.0.1)
bump-my-version bump patch
# Bump minor version (1.0.0 → 1.1.0)
bump-my-version bump minor
# Bump major version (1.0.0 → 2.0.0)
bump-my-version bump major
# Show what would be changed (dry run)
bump-my-version bump --dry-run --verbose patch
```
#### Package Publishing
```bash
# Install publishing tools
pip install build twine
# Build the package
python -m build
# Upload to Test PyPI (recommended first)
twine upload --repository testpypi dist/*
# Upload to production PyPI
twine upload dist/*
# Check package on PyPI
pip install binoauth # test installation
# Automated release (recommended)
./release.sh patch # or minor/major
```
#### Release Process
The project includes an automated release script that handles the complete publishing workflow:
```bash
# Make sure you're on main branch with clean working directory
git checkout main
git pull origin main
# Run automated release (handles testing, building, and publishing)
./release.sh patch # for bug fixes (1.0.0 → 1.0.1)
./release.sh minor # for new features (1.0.0 → 1.1.0)
./release.sh major # for breaking changes (1.0.0 → 2.0.0)
```
The release script:
1. Verifies you're on main branch with clean working directory
2. Runs all tests and quality checks
3. Shows version bump preview and asks for confirmation
4. Bumps version and creates git commit/tag
5. Builds the package (source + wheel)
6. Uploads to Test PyPI first for verification
7. Asks for final confirmation before production upload
8. Uploads to production PyPI
9. Pushes git tag to remote repository
**Prerequisites for publishing:**
- PyPI account with API tokens
- Configure `~/.pypirc` with your tokens (see `.pypirc.template`)
```
## Architecture
### Package Structure
```shell
binoauth/
├── __init__.py # Main SDK with convenience wrappers
├── admin/ # Admin API (auto-generated)
│ ├── api/ # API endpoint classes
│ ├── models/ # Pydantic data models
│ ├── docs/ # Auto-generated documentation
│ └── test/ # Unit tests
└── tenant/ # Tenant API (auto-generated)
├── api/ # API endpoint classes
├── models/ # Pydantic data models
├── docs/ # Auto-generated documentation
└── test/ # Unit tests
```
### High-Level Design
The SDK provides two main convenience wrapper classes:
- **`BinoauthAdmin`**: Wraps the admin API for tenant/client/user management
- **`BinoauthTenant`**: Wraps the tenant API for authentication operations
Both classes handle:
- Configuration management
- Multiple authentication methods
- Context manager support
- Error handling
### Code Generation
The `binoauth/admin/` and `binoauth/tenant/` directories contain auto-generated code from OpenAPI specifications. **Never manually edit files in these directories.**
The `./codegen.sh` script:
1. Downloads latest OpenAPI specs from production endpoints
2. Generates Python clients using OpenAPI Generator
3. Maintains unified package structure
4. Preserves manually maintained convenience wrappers
## Authentication Methods
### 1. API Keys (Recommended for Backend Services)
```python
tenant = BinoauthTenant(
host="https://tenant.auth.example.com",
api_key="your_api_key"
)
```
### 2. Bearer Tokens (OAuth2/JWT)
```python
admin = BinoauthAdmin(
host="https://api.auth.example.com",
access_token="your_jwt_token"
)
```
### 3. Session Cookies
Session authentication is handled automatically by the underlying HTTP client when cookies are present.
## Contributing
1. **Code Style**: This project uses Black (88 character line length) and isort for formatting
2. **Type Hints**: All new code should include proper type annotations
3. **Testing**: Write tests for new functionality in the appropriate test directories
4. **Linting**: All code must pass flake8, mypy, and other quality checks
5. **Pre-commit**: Install and use pre-commit hooks for automated quality checks
### Important Notes
- **Auto-generated Code**: Never edit files in `binoauth/admin/` or `binoauth/tenant/` directories
- **Version Management**: Use `bump-my-version` for version updates
- **Dependencies**: Keep core dependencies minimal; add development tools to `[dev]` extra
- **Multi-tenant Architecture**: Admin API operates on public tenant, Tenant API is tenant-specific
## License
MIT
## Support
coming soon!
Raw data
{
"_id": null,
"home_page": null,
"name": "binoauth",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "authentication, authorization, oauth2, openid-connect, api, sdk, multi-tenant",
"author": null,
"author_email": "Binoauth <support@binoauth.com>",
"download_url": "https://files.pythonhosted.org/packages/15/22/1291e7541da55255180f5649decf64cd28be08a9f9f26b6ed5abd04c9466/binoauth-0.0.3.tar.gz",
"platform": null,
"description": "# Binoauth Python SDK\n\nA multi-tenant authentication and authorization Python SDK that supports OAuth2, OpenID Connect, API keys, and multiple authentication methods.\n\n## Features\n\n- **Admin API**: Management endpoints for tenants, clients, users, API keys, and provider settings\n- **Tenant API**: Authentication endpoints for login, signup, OAuth2 flows, magic links, phone OTP, and user profile management\n- **Multiple Authentication Methods**: API keys, Bearer tokens, session cookies\n- **Auto-generated from OpenAPI**: Always up-to-date with the latest API specifications\n- **Type-safe**: Full type hints and Pydantic models\n- **Python 3.9+**: Modern Python support\n\n## Installation\n\n```bash\npip install binoauth\n```\n\nFor development:\n```bash\npip install -e .[dev]\n```\n\n## Quick Start\n\n### Admin API Usage\n\n```python\nfrom binoauth import BinoauthAdmin\n\n# Initialize admin client\nadmin = BinoauthAdmin(\n host=\"https://api.auth.example.com\",\n access_token=\"your_admin_token\"\n)\n\n# List tenants\ntenants = admin.api.list_tenants_api_v1_tenants_get()\n\n# Create a new client\nclient_data = {\n \"name\": \"My App\",\n \"redirect_uris\": [\"https://myapp.com/callback\"]\n}\nnew_client = admin.api.create_client_api_v1_clients_post(client_data)\n```\n\n### Tenant API Usage\n\n```python\nfrom binoauth import BinoauthTenant\n\n# Initialize tenant client\ntenant = BinoauthTenant(\n host=\"https://tenant.auth.example.com\",\n api_key=\"your_api_key\"\n)\n\n# User signup\nsignup_data = {\n \"email\": \"user@example.com\",\n \"password\": \"secure_password\"\n}\nresponse = tenant.auth.signup_api_v1_auth_signup_post(signup_data)\n\n# OAuth2 authorization\nauth_url = tenant.oauth2.authorize_api_v1_oauth2_authorize_get(\n client_id=\"your_client_id\",\n redirect_uri=\"https://yourapp.com/callback\",\n response_type=\"code\"\n)\n```\n\n### Context Manager Usage\n\n```python\n# Both classes support context managers\nwith BinoauthAdmin(host=\"...\", access_token=\"...\") as admin:\n tenants = admin.api.list_tenants_api_v1_tenants_get()\n\nwith BinoauthTenant(host=\"...\", api_key=\"...\") as tenant:\n response = tenant.auth.login_api_v1_auth_login_post(login_data)\n```\n\n## Development Setup\n\n### Prerequisites\n\n- Python 3.9+\n- Git\n- OpenAPI Generator CLI (for code generation)\n\n### Development Installation\n\n1. Clone the repository:\n```bash\ngit clone <repository-url>\ncd binoauth-python-sdk\n```\n\n2. Install development dependencies:\n```bash\npip install -e .[dev]\n```\n\n3. Install pre-commit hooks:\n```bash\npre-commit install\n```\n\n### Development Commands\n\n#### Code Generation\n```bash\n# Regenerate SDK from latest OpenAPI specs\n./codegen.sh\n```\n\n#### Testing\n```bash\n# Run all tests\npython -m pytest\n\n# Run tests with coverage\npython -m pytest --cov=binoauth\n\n# Run specific test file\npython -m pytest binoauth/admin/test/test_admin_api.py\n```\n\n#### Code Quality & Linting\n```bash\n# Format code\nblack binoauth/\n\n# Sort imports\nisort binoauth/\n\n# Lint code\nflake8 binoauth/\n\n# Type checking (manual only, auto-generated code conflicts)\nmypy binoauth/__init__.py --ignore-missing-imports --allow-untyped-calls\n\n# Run all quality checks\npre-commit run --all-files\n```\n\n#### Version Management\n```bash\n# Bump patch version (1.0.0 \u2192 1.0.1)\nbump-my-version bump patch\n\n# Bump minor version (1.0.0 \u2192 1.1.0)\nbump-my-version bump minor\n\n# Bump major version (1.0.0 \u2192 2.0.0)\nbump-my-version bump major\n\n# Show what would be changed (dry run)\nbump-my-version bump --dry-run --verbose patch\n```\n\n#### Package Publishing\n```bash\n# Install publishing tools\npip install build twine\n\n# Build the package\npython -m build\n\n# Upload to Test PyPI (recommended first)\ntwine upload --repository testpypi dist/*\n\n# Upload to production PyPI\ntwine upload dist/*\n\n# Check package on PyPI\npip install binoauth # test installation\n\n# Automated release (recommended)\n./release.sh patch # or minor/major\n```\n\n#### Release Process\n\nThe project includes an automated release script that handles the complete publishing workflow:\n\n```bash\n# Make sure you're on main branch with clean working directory\ngit checkout main\ngit pull origin main\n\n# Run automated release (handles testing, building, and publishing)\n./release.sh patch # for bug fixes (1.0.0 \u2192 1.0.1)\n./release.sh minor # for new features (1.0.0 \u2192 1.1.0)\n./release.sh major # for breaking changes (1.0.0 \u2192 2.0.0)\n```\n\nThe release script:\n1. Verifies you're on main branch with clean working directory\n2. Runs all tests and quality checks\n3. Shows version bump preview and asks for confirmation\n4. Bumps version and creates git commit/tag\n5. Builds the package (source + wheel)\n6. Uploads to Test PyPI first for verification\n7. Asks for final confirmation before production upload\n8. Uploads to production PyPI\n9. Pushes git tag to remote repository\n\n**Prerequisites for publishing:**\n- PyPI account with API tokens\n- Configure `~/.pypirc` with your tokens (see `.pypirc.template`)\n\n```\n\n## Architecture\n\n### Package Structure\n\n```shell\nbinoauth/\n\u251c\u2500\u2500 __init__.py # Main SDK with convenience wrappers\n\u251c\u2500\u2500 admin/ # Admin API (auto-generated)\n\u2502 \u251c\u2500\u2500 api/ # API endpoint classes\n\u2502 \u251c\u2500\u2500 models/ # Pydantic data models\n\u2502 \u251c\u2500\u2500 docs/ # Auto-generated documentation\n\u2502 \u2514\u2500\u2500 test/ # Unit tests\n\u2514\u2500\u2500 tenant/ # Tenant API (auto-generated)\n \u251c\u2500\u2500 api/ # API endpoint classes\n \u251c\u2500\u2500 models/ # Pydantic data models\n \u251c\u2500\u2500 docs/ # Auto-generated documentation\n \u2514\u2500\u2500 test/ # Unit tests\n```\n\n### High-Level Design\n\nThe SDK provides two main convenience wrapper classes:\n\n- **`BinoauthAdmin`**: Wraps the admin API for tenant/client/user management\n- **`BinoauthTenant`**: Wraps the tenant API for authentication operations\n\nBoth classes handle:\n- Configuration management\n- Multiple authentication methods\n- Context manager support\n- Error handling\n\n### Code Generation\n\nThe `binoauth/admin/` and `binoauth/tenant/` directories contain auto-generated code from OpenAPI specifications. **Never manually edit files in these directories.**\n\nThe `./codegen.sh` script:\n1. Downloads latest OpenAPI specs from production endpoints\n2. Generates Python clients using OpenAPI Generator\n3. Maintains unified package structure\n4. Preserves manually maintained convenience wrappers\n\n## Authentication Methods\n\n### 1. API Keys (Recommended for Backend Services)\n```python\ntenant = BinoauthTenant(\n host=\"https://tenant.auth.example.com\",\n api_key=\"your_api_key\"\n)\n```\n\n### 2. Bearer Tokens (OAuth2/JWT)\n```python\nadmin = BinoauthAdmin(\n host=\"https://api.auth.example.com\",\n access_token=\"your_jwt_token\"\n)\n```\n\n### 3. Session Cookies\nSession authentication is handled automatically by the underlying HTTP client when cookies are present.\n\n## Contributing\n\n1. **Code Style**: This project uses Black (88 character line length) and isort for formatting\n2. **Type Hints**: All new code should include proper type annotations\n3. **Testing**: Write tests for new functionality in the appropriate test directories\n4. **Linting**: All code must pass flake8, mypy, and other quality checks\n5. **Pre-commit**: Install and use pre-commit hooks for automated quality checks\n\n### Important Notes\n\n- **Auto-generated Code**: Never edit files in `binoauth/admin/` or `binoauth/tenant/` directories\n- **Version Management**: Use `bump-my-version` for version updates\n- **Dependencies**: Keep core dependencies minimal; add development tools to `[dev]` extra\n- **Multi-tenant Architecture**: Admin API operates on public tenant, Tenant API is tenant-specific\n\n## License\nMIT\n\n## Support\ncoming soon!\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Multi-tenant authentication and authorization Python SDK supporting OAuth2, OpenID Connect, API keys, and multiple authentication methods",
"version": "0.0.3",
"project_urls": {
"Bug Tracker": "https://github.com/binoauth/binoauth-python-sdk/issues",
"Documentation": "https://docs.binoauth.com",
"Homepage": "https://binoauth.com",
"Repository": "https://github.com/binoauth/binoauth-python-sdk"
},
"split_keywords": [
"authentication",
" authorization",
" oauth2",
" openid-connect",
" api",
" sdk",
" multi-tenant"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0a9ecf3ff6e7ec91c97b06f2b679e5e49446832b1e64408511b2c98a38cddec5",
"md5": "a4da21fe3008ac0764e27d8edc0e4069",
"sha256": "2d49f3f5864a3b385256aae901f6872e8bd3beeda8ccee8e2034ce4c71f218d9"
},
"downloads": -1,
"filename": "binoauth-0.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a4da21fe3008ac0764e27d8edc0e4069",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 318405,
"upload_time": "2025-08-04T00:27:55",
"upload_time_iso_8601": "2025-08-04T00:27:55.077803Z",
"url": "https://files.pythonhosted.org/packages/0a/9e/cf3ff6e7ec91c97b06f2b679e5e49446832b1e64408511b2c98a38cddec5/binoauth-0.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "15221291e7541da55255180f5649decf64cd28be08a9f9f26b6ed5abd04c9466",
"md5": "81f0e834bbdc334a806cbfa32e36ec50",
"sha256": "194dd763980172e992cebb99b25811e8a3001d13914b0ec6aa15b6fdb2ad050c"
},
"downloads": -1,
"filename": "binoauth-0.0.3.tar.gz",
"has_sig": false,
"md5_digest": "81f0e834bbdc334a806cbfa32e36ec50",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 103710,
"upload_time": "2025-08-04T00:27:57",
"upload_time_iso_8601": "2025-08-04T00:27:57.264691Z",
"url": "https://files.pythonhosted.org/packages/15/22/1291e7541da55255180f5649decf64cd28be08a9f9f26b6ed5abd04c9466/binoauth-0.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-04 00:27:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "binoauth",
"github_project": "binoauth-python-sdk",
"github_not_found": true,
"lcname": "binoauth"
}
JSON
