civic-auth

Name	civic-auth JSON
Version	0.1.2 JSON
	download
home_page	None
Summary	Python SDK for Civic Auth server-side authentication
upload_time	2025-07-25 14:12:38
maintainer	None
docs_url	None
author	None
requires_python	>=3.8
license	MIT
keywords	auth authentication civic oauth oidc
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # Civic Auth Python SDK

[![PyPI version](https://badge.fury.io/py/civic-auth.svg)](https://pypi.org/project/civic-auth/)
[![Python Versions](https://img.shields.io/pypi/pyversions/civic-auth.svg)](https://pypi.org/project/civic-auth/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Python SDK for Civic Auth server-side authentication. This library provides a Python implementation that matches the API of the [Node.js Civic Auth library](https://github.com/civicteam/civic-auth).

## What is Civic Auth?

Civic Auth is a flexible authentication and user management solution that provides seamless sign-in experiences for your applications. It supports multiple authentication methods including email, Google, passkeys, and wallet-based authentication, making it suitable for both traditional web applications and Web3 projects.

Key features:
- **Multiple sign-in options** - Email, social providers, passkeys, and Web3 wallets
- **Privacy-preserving** - Built with user privacy at its core
- **Flexible integration** - Works with any web framework
- **Embedded wallets** - Optional Web3 capabilities for blockchain applications
- **User verification** - Support for identity proofs and credentials

## Installation

```bash
pip install civic-auth
```

For specific framework support:

```bash
# Flask
pip install "civic-auth[flask]"

# FastAPI
pip install "civic-auth[fastapi]"

# Django
pip install "civic-auth[django]"
```

## Quick Start

### FastAPI Integration

[Full example →](examples/fastapi/)

```python
from fastapi import FastAPI, Depends
from civic_auth.integrations.fastapi import create_auth_router, create_auth_dependencies

app = FastAPI()

# Configure
config = {
    "client_id": "your-client-id",  # Get this from auth.civic.com
    "redirect_url": "..."
}

# Add auth routes  
app.include_router(create_auth_router(config))

# Create dependencies
civic_auth_dep, get_current_user, require_auth = create_auth_dependencies(config)

# Protected route
@app.get("/protected", dependencies=[Depends(require_auth)])
async def protected(user = Depends(get_current_user)):
    return f"Hello {user.name}!"
```

### Flask Integration

[Full example →](examples/flask/)

```python
from flask import Flask
from civic_auth.integrations.flask import init_civic_auth, create_auth_blueprint, civic_auth_required

app = Flask(__name__)

# Configure and initialize
config = {
    "client_id": "your-client-id",  # Get this from auth.civic.com
    "redirect_url": "..."
}
init_civic_auth(app, config)
app.register_blueprint(create_auth_blueprint(config))

# Protected route
@app.route("/protected")
@civic_auth_required
async def protected():
    # user available via get_civic_user()
    ...
```

### Django Integration

[Full example →](examples/django/)

```python
# settings.py
MIDDLEWARE = [
    # ...
    'civic_auth.integrations.django.CivicAuthMiddleware',
]

CIVIC_AUTH = {
    'client_id': 'your-client-id',  # Get this from auth.civic.com
    'redirect_url': '...',
}

# urls.py
from civic_auth.integrations.django import get_auth_urls
urlpatterns = [
    path('', include(get_auth_urls())),  # Adds /auth/* routes
    # ...
]

# views.py
from civic_auth.integrations.django import civic_auth_required

@civic_auth_required
def protected(request):
    # user available via request.civic_user
    ...
```

### Other Frameworks

```python
from civic_auth import CivicAuth
from civic_auth.storage import AuthStorage

class MyStorage(AuthStorage):
    # Implement get/set/delete for your framework's session/cookies
    ...

storage = MyStorage()
civic_auth = CivicAuth(storage, config)

# Use the API
login_url = await civic_auth.build_login_url()
await civic_auth.resolve_oauth_access_code(code, state)
user = await civic_auth.get_user()
```

## API Reference

### CivicAuth Class

#### Methods

- `get_user()` - Get the authenticated user information
- `get_tokens()` - Get the stored OAuth tokens
- `is_logged_in()` - Check if user is authenticated
- `build_login_url(scopes=None)` - Build OAuth authorization URL
- `resolve_oauth_access_code(code, state)` - Exchange auth code for tokens
- `refresh_tokens()` - Refresh access tokens
- `build_logout_redirect_url()` - Build logout URL
- `clear_tokens()` - Clear all stored tokens

### Types

```python
from civic_auth.types import BaseUser, AuthConfig, Tokens

# BaseUser
{
    "id": str,
    "email": Optional[str],
    "username": Optional[str],
    "name": Optional[str],
    "given_name": Optional[str],
    "family_name": Optional[str],
    "picture": Optional[str],
    "updated_at": Optional[datetime]
}

# AuthConfig
{
    "client_id": str,  # Required - Get this from auth.civic.com
    "redirect_url": str,  # Required
    "oauth_server": Optional[str],  # Default: "https://auth.civic.com/oauth"
    "post_logout_redirect_url": Optional[str],
    "scopes": Optional[List[str]]  # Default: ["openid", "email", "profile"]
}

# Tokens
{
    "access_token": str,
    "id_token": str,
    "refresh_token": Optional[str],
    "token_type": str,
    "expires_in": Optional[int],
    "scope": Optional[str]
}
```

## Examples

See the [examples](examples/) directory for complete working examples:

- [Flask Example](examples/flask/)
- [FastAPI Example](examples/fastapi/)
- [Django Example](examples/django/)

## Development

### Setup

```bash
# Clone the repository
git clone https://github.com/civicteam/civic-auth-py.git
cd civic-auth-py

# Create a virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode with all dependencies
pip install -e ".[dev,all]"
```

### Testing

```bash
# Run tests
pytest

# Run with coverage
pytest --cov=civic_auth
```

### Linting and Formatting

```bash
# Format code
black civic_auth tests

# Lint
ruff civic_auth tests

# Type checking
mypy civic_auth
```

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Support

For issues and questions:
- GitHub Issues: [https://github.com/civicteam/civic-auth-py/issues](https://github.com/civicteam/civic-auth-py/issues)
- Documentation: [https://docs.civic.com](https://docs.civic.com)
            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "civic-auth",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.8",
    "maintainer_email": null,
    "keywords": "auth, authentication, civic, oauth, oidc",
    "author": null,
    "author_email": "Daniel Kelleher <daniel@civic.com>",
    "download_url": "https://files.pythonhosted.org/packages/7f/4e/63cfd8ef102f05fd14f1e4e86df66751ce4a1f57c42cae229417d6cc1ae9/civic_auth-0.1.2.tar.gz",
    "platform": null,
    "description": "# Civic Auth Python SDK\n\n[![PyPI version](https://badge.fury.io/py/civic-auth.svg)](https://pypi.org/project/civic-auth/)\n[![Python Versions](https://img.shields.io/pypi/pyversions/civic-auth.svg)](https://pypi.org/project/civic-auth/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nPython SDK for Civic Auth server-side authentication. This library provides a Python implementation that matches the API of the [Node.js Civic Auth library](https://github.com/civicteam/civic-auth).\n\n## What is Civic Auth?\n\nCivic Auth is a flexible authentication and user management solution that provides seamless sign-in experiences for your applications. It supports multiple authentication methods including email, Google, passkeys, and wallet-based authentication, making it suitable for both traditional web applications and Web3 projects.\n\nKey features:\n- **Multiple sign-in options** - Email, social providers, passkeys, and Web3 wallets\n- **Privacy-preserving** - Built with user privacy at its core\n- **Flexible integration** - Works with any web framework\n- **Embedded wallets** - Optional Web3 capabilities for blockchain applications\n- **User verification** - Support for identity proofs and credentials\n\n## Installation\n\n```bash\npip install civic-auth\n```\n\nFor specific framework support:\n\n```bash\n# Flask\npip install \"civic-auth[flask]\"\n\n# FastAPI\npip install \"civic-auth[fastapi]\"\n\n# Django\npip install \"civic-auth[django]\"\n```\n\n## Quick Start\n\n### FastAPI Integration\n\n[Full example \u2192](examples/fastapi/)\n\n```python\nfrom fastapi import FastAPI, Depends\nfrom civic_auth.integrations.fastapi import create_auth_router, create_auth_dependencies\n\napp = FastAPI()\n\n# Configure\nconfig = {\n    \"client_id\": \"your-client-id\",  # Get this from auth.civic.com\n    \"redirect_url\": \"...\"\n}\n\n# Add auth routes  \napp.include_router(create_auth_router(config))\n\n# Create dependencies\ncivic_auth_dep, get_current_user, require_auth = create_auth_dependencies(config)\n\n# Protected route\n@app.get(\"/protected\", dependencies=[Depends(require_auth)])\nasync def protected(user = Depends(get_current_user)):\n    return f\"Hello {user.name}!\"\n```\n\n### Flask Integration\n\n[Full example \u2192](examples/flask/)\n\n```python\nfrom flask import Flask\nfrom civic_auth.integrations.flask import init_civic_auth, create_auth_blueprint, civic_auth_required\n\napp = Flask(__name__)\n\n# Configure and initialize\nconfig = {\n    \"client_id\": \"your-client-id\",  # Get this from auth.civic.com\n    \"redirect_url\": \"...\"\n}\ninit_civic_auth(app, config)\napp.register_blueprint(create_auth_blueprint(config))\n\n# Protected route\n@app.route(\"/protected\")\n@civic_auth_required\nasync def protected():\n    # user available via get_civic_user()\n    ...\n```\n\n### Django Integration\n\n[Full example \u2192](examples/django/)\n\n```python\n# settings.py\nMIDDLEWARE = [\n    # ...\n    'civic_auth.integrations.django.CivicAuthMiddleware',\n]\n\nCIVIC_AUTH = {\n    'client_id': 'your-client-id',  # Get this from auth.civic.com\n    'redirect_url': '...',\n}\n\n# urls.py\nfrom civic_auth.integrations.django import get_auth_urls\nurlpatterns = [\n    path('', include(get_auth_urls())),  # Adds /auth/* routes\n    # ...\n]\n\n# views.py\nfrom civic_auth.integrations.django import civic_auth_required\n\n@civic_auth_required\ndef protected(request):\n    # user available via request.civic_user\n    ...\n```\n\n### Other Frameworks\n\n```python\nfrom civic_auth import CivicAuth\nfrom civic_auth.storage import AuthStorage\n\nclass MyStorage(AuthStorage):\n    # Implement get/set/delete for your framework's session/cookies\n    ...\n\nstorage = MyStorage()\ncivic_auth = CivicAuth(storage, config)\n\n# Use the API\nlogin_url = await civic_auth.build_login_url()\nawait civic_auth.resolve_oauth_access_code(code, state)\nuser = await civic_auth.get_user()\n```\n\n## API Reference\n\n### CivicAuth Class\n\n#### Methods\n\n- `get_user()` - Get the authenticated user information\n- `get_tokens()` - Get the stored OAuth tokens\n- `is_logged_in()` - Check if user is authenticated\n- `build_login_url(scopes=None)` - Build OAuth authorization URL\n- `resolve_oauth_access_code(code, state)` - Exchange auth code for tokens\n- `refresh_tokens()` - Refresh access tokens\n- `build_logout_redirect_url()` - Build logout URL\n- `clear_tokens()` - Clear all stored tokens\n\n### Types\n\n```python\nfrom civic_auth.types import BaseUser, AuthConfig, Tokens\n\n# BaseUser\n{\n    \"id\": str,\n    \"email\": Optional[str],\n    \"username\": Optional[str],\n    \"name\": Optional[str],\n    \"given_name\": Optional[str],\n    \"family_name\": Optional[str],\n    \"picture\": Optional[str],\n    \"updated_at\": Optional[datetime]\n}\n\n# AuthConfig\n{\n    \"client_id\": str,  # Required - Get this from auth.civic.com\n    \"redirect_url\": str,  # Required\n    \"oauth_server\": Optional[str],  # Default: \"https://auth.civic.com/oauth\"\n    \"post_logout_redirect_url\": Optional[str],\n    \"scopes\": Optional[List[str]]  # Default: [\"openid\", \"email\", \"profile\"]\n}\n\n# Tokens\n{\n    \"access_token\": str,\n    \"id_token\": str,\n    \"refresh_token\": Optional[str],\n    \"token_type\": str,\n    \"expires_in\": Optional[int],\n    \"scope\": Optional[str]\n}\n```\n\n## Examples\n\nSee the [examples](examples/) directory for complete working examples:\n\n- [Flask Example](examples/flask/)\n- [FastAPI Example](examples/fastapi/)\n- [Django Example](examples/django/)\n\n## Development\n\n### Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/civicteam/civic-auth-py.git\ncd civic-auth-py\n\n# Create a virtual environment (recommended)\npython -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\n\n# Install in development mode with all dependencies\npip install -e \".[dev,all]\"\n```\n\n### Testing\n\n```bash\n# Run tests\npytest\n\n# Run with coverage\npytest --cov=civic_auth\n```\n\n### Linting and Formatting\n\n```bash\n# Format code\nblack civic_auth tests\n\n# Lint\nruff civic_auth tests\n\n# Type checking\nmypy civic_auth\n```\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## Support\n\nFor issues and questions:\n- GitHub Issues: [https://github.com/civicteam/civic-auth-py/issues](https://github.com/civicteam/civic-auth-py/issues)\n- Documentation: [https://docs.civic.com](https://docs.civic.com)",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "Python SDK for Civic Auth server-side authentication",
    "version": "0.1.2",
    "project_urls": {
        "Documentation": "https://docs.civic.com",
        "Homepage": "https://github.com/civicteam/civic-auth-py",
        "Issues": "https://github.com/civicteam/civic-auth-py/issues",
        "Repository": "https://github.com/civicteam/civic-auth-py"
    },
    "split_keywords": [
        "auth",
        " authentication",
        " civic",
        " oauth",
        " oidc"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "c1781cca689de4de0aaa391da004f3720e1503186d0d15f71bb4b011fa850694",
                "md5": "9b2a2fde2c6a4c3c27db0f9f6ddccf90",
                "sha256": "0bf1bff7e90d75e0d9468b69852ff9c04c90566b73ef58274173008cf740382c"
            },
            "downloads": -1,
            "filename": "civic_auth-0.1.2-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "9b2a2fde2c6a4c3c27db0f9f6ddccf90",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.8",
            "size": 16773,
            "upload_time": "2025-07-25T14:12:37",
            "upload_time_iso_8601": "2025-07-25T14:12:37.478404Z",
            "url": "https://files.pythonhosted.org/packages/c1/78/1cca689de4de0aaa391da004f3720e1503186d0d15f71bb4b011fa850694/civic_auth-0.1.2-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "7f4e63cfd8ef102f05fd14f1e4e86df66751ce4a1f57c42cae229417d6cc1ae9",
                "md5": "d0b25390d476d08ceccfd8cf1b491bfd",
                "sha256": "620fd788037579b74307beac94bb83923bb6ac63c50e22ed3a1d307d3d8a1b2c"
            },
            "downloads": -1,
            "filename": "civic_auth-0.1.2.tar.gz",
            "has_sig": false,
            "md5_digest": "d0b25390d476d08ceccfd8cf1b491bfd",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.8",
            "size": 22863,
            "upload_time": "2025-07-25T14:12:38",
            "upload_time_iso_8601": "2025-07-25T14:12:38.763599Z",
            "url": "https://files.pythonhosted.org/packages/7f/4e/63cfd8ef102f05fd14f1e4e86df66751ce4a1f57c42cae229417d6cc1ae9/civic_auth-0.1.2.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-07-25 14:12:38",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "civicteam",
    "github_project": "civic-auth-py",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "civic-auth"
}