Skip to main content

authfn Python SDK

API key authentication library using Superfunctions abstractions for Python

Python implementation of authfn with async/await support for API key-based authentication.

Overview

authfn is a reference implementation of authentication that provides API key-based authentication. It includes:

  • Auth Provider: Async authentication and authorization
  • Database Storage: Uses database adapters for storing API keys
  • Key Management: Secure API key generation and validation
  • Type Safety: Full type hints with Pydantic models

Installation

pip install authfn

Quick Start

1. Setup Database

You'll need a database adapter that implements the DatabaseAdapter protocol:

from authfn.types import DatabaseAdapter, WhereClause, OrderByClause
from typing import Any, Dict, List, Optional


class MyDatabaseAdapter:
    """Your database adapter implementation."""
    
    async def find_one(
        self,
        model: str,
        where: List[WhereClause],
        namespace: str,
    ) -> Optional[Dict[str, Any]]:
        # Your implementation here
        pass
    
    async def find_many(
        self,
        model: str,
        where: List[WhereClause],
        order_by: Optional[List[OrderByClause]],
        namespace: str,
    ) -> List[Dict[str, Any]]:
        # Your implementation here
        pass
    
    async def create(
        self,
        model: str,
        data: Dict[str, Any],
        namespace: str,
    ) -> None:
        # Your implementation here
        pass
    
    async def update(
        self,
        model: str,
        where: List[WhereClause],
        data: Dict[str, Any],
        namespace: str,
    ) -> None:
        # Your implementation here
        pass

2. Create authfn Instance

from authfn import create_authfn, AuthFnConfig

adapter = MyDatabaseAdapter()

auth = create_authfn(
    AuthFnConfig(
        database=adapter,
        namespace="authfn",
        enable_api=True,
        api_config={
            "admin_key": "your-admin-key",  # Optional: protect management API
        },
    )
)

3. Create API Keys

from authfn.types import ApiKeyCreate

# Create a new API key
result = await auth.create_key(
    ApiKeyCreate(
        name="Production API Key",
        resourceIds=["resource-1", "resource-2"],
        scopes=["read", "write"],
        metadata={"environment": "production"},
    )
)

print(f"API Key ID: {result.id}")
print(f"API Key: {result.key}")  # Save this securely!

4. Authenticate Requests

from authfn.types import Request

class MyRequest:
    """Your request wrapper."""
    
    def __init__(self, headers: Dict[str, str]):
        self._headers = headers
    
    @property
    def headers(self) -> Dict[str, str]:
        return self._headers


# Authenticate a request
request = MyRequest({"Authorization": "Bearer ak_..."})

try:
    session = await auth.provider.authenticate(request)
    if session:
        print(f"Authenticated as: {session.name}")
        print(f"Resource IDs: {session.resource_ids}")
        print(f"Scopes: {session.scopes}")
except Exception as e:
    print(f"Authentication failed: {e}")

5. Authorize Resource Access

# Check if session has access to a resource
if session:
    has_access = await auth.provider.authorize(session, "resource-1")
    if has_access:
        print("Access granted to resource-1")
    else:
        print("Access denied to resource-1")

6. Manage API Keys

# Get API key by ID
key = await auth.get_key("key_...")
if key:
    print(f"Key name: {key.name}")
    print(f"Created at: {key.created_at}")

# List all API keys
keys = await auth.list_keys()
for key in keys:
    print(f"- {key.name} ({key.id})")

# List keys for a specific resource
keys = await auth.list_keys(filters={"resourceId": "resource-1"})

# Revoke an API key
await auth.revoke_key("key_...")

Complete Example

import asyncio
from authfn import create_authfn, AuthFnConfig
from authfn.types import ApiKeyCreate


async def main():
    # Setup (you would use your actual database adapter)
    adapter = MyDatabaseAdapter()
    
    auth = create_authfn(
        AuthFnConfig(
            database=adapter,
            namespace="authfn",
        )
    )
    
    # Create an API key
    result = await auth.create_key(
        ApiKeyCreate(
            name="My App Key",
            resourceIds=["app-1", "app-2"],
            scopes=["read", "write"],
        )
    )
    
    print(f"Created API key: {result.key}")
    
    # Simulate authentication
    class SimpleRequest:
        def __init__(self, token: str):
            self._headers = {"Authorization": f"Bearer {token}"}
        
        @property
        def headers(self):
            return self._headers
    
    request = SimpleRequest(result.key)
    session = await auth.provider.authenticate(request)
    
    if session:
        print(f"Authenticated as: {session.name}")
        
        # Check authorization
        can_access = await auth.provider.authorize(session, "app-1")
        print(f"Can access app-1: {can_access}")


if __name__ == "__main__":
    asyncio.run(main())

Schema Definition

Get the schema definition for creating database tables:

from authfn.schema import get_schema

schema = get_schema({"namespace": "authfn"})
print(schema)
# {
#   "version": 1,
#   "schemas": [
#     {
#       "modelName": "apiKeys",
#       "fields": {...},
#       "indexes": [...]
#     }
#   ]
# }

API Reference

create_authfn(config: AuthFnConfig) -> AuthFn

Create an authfn instance.

AuthFn

Main authfn class with the following methods:

  • provider: AuthFnProvider - Auth provider for authentication
  • async create_key(data: ApiKeyCreate) -> ApiKeyResponse - Create a new API key
  • async revoke_key(key_id: str) -> None - Revoke an API key
  • async get_key(key_id: str) -> Optional[ApiKeySanitized] - Get an API key by ID
  • async list_keys(filters: Optional[Dict]) -> List[ApiKeySanitized] - List API keys

AuthFnProvider

Auth provider with the following methods:

  • async authenticate(request: Request) -> Optional[ApiKeySession] - Authenticate a request
  • async authorize(session: ApiKeySession, resource_id: str) -> bool - Authorize resource access
  • async revoke(session_id: str) -> None - Revoke a session

Type Safety

The SDK uses Pydantic models for full type safety:

from authfn.types import (
    ApiKey,
    ApiKeyCreate,
    ApiKeyResponse,
    ApiKeySanitized,
    ApiKeySession,
    AuthFnConfig,
)

Error Handling

from authfn.types import (
    InvalidCredentialsError,
    ExpiredCredentialsError,
    UnauthorizedError,
    NotFoundError,
)

try:
    session = await auth.provider.authenticate(request)
except InvalidCredentialsError:
    print("Invalid API key")
except ExpiredCredentialsError:
    print("API key has expired")

Development

# Install dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Type checking
mypy authfn

# Linting
ruff check authfn

# Format code
black authfn

License

MIT

Repository

https://github.com/21nCo/super-functions

Metadata

Release files for authfn 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for authfn 0.1.0
File Size Uploaded Provenance Actions
authfn-0.1.0.tar.gz 26.4 kB Without provenance Details for authfn-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for authfn 0.1.0
File Interpreter ABI Platform Actions
authfn-0.1.0-py3-none-any.whl Python 3 none any Details for authfn-0.1.0-py3-none-any.whl

Total release size: 35.5 kB

Release files / authfn-0.1.0.tar.gz

Download URL authfn-0.1.0.tar.gz
Size 26.4 kB
Tags Source
SHA-256 checksum
How to use checksums
17489d8aeb83badaf8d2863e806dff798e93eba130c3dd8fd4986bb0bf0c84c6
BLAKE2b-256 checksum
How to use checksums
8654b87a87049d707b8571e436b772d551fcbe9910a1342088f5d4d50564e0f3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.3

Release files / authfn-0.1.0-py3-none-any.whl

Download URL authfn-0.1.0-py3-none-any.whl
Size 9.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7c08300158f9189655d710b99a8815c9888813aee092b57645acfacbfae63ee6
BLAKE2b-256 checksum
How to use checksums
1402cd518994079b56c5ed1798864db37d86100e8c4f97ff831cd45ce004daf6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.3

Security for authfn 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page