Guides
Audience: App developers who want to learn about specific ActingWeb features in depth.
This section provides detailed guides for implementing ActingWeb features in your application.
Contents
- ActingWeb Authentication System
- Overview
- Architecture
- Authentication Methods
- Provider Implementations
- Factory Functions
- OAuth2 Flow
- MCP Integration
- Custom Route Authentication
- Implementation Files
- Security Considerations
- Error Handling
- Testing
- Backward Compatibility
- Migration from Legacy
- Email Verification System
- MCP Authorization Security
- Provider ID Support
- Mobile App OAuth2
- Future Enhancements
- OAuth2 Client Management System
- OAuth Login Flow with Postponed Actor Creation
- Sign in with Apple
- SPA Authentication Guide
- Understanding ActingWeb’s Two OAuth2 Roles
- Overview
- Token Architecture
- Getting Started
- Token Delivery Modes
- PKCE Support
- Native id_token (JWT-bearer) grant
- Mobile-ticket grant (server-side code exchange)
- Token Refresh with Rotation
- Mobile App Authentication
- Session Management
- Complete Example
- Security Best Practices
- Alternative: Factory JSON API
- API Reference
- Troubleshooting
- Migration from Standard OAuth
- ActingWeb Access Control (Simple Guide)
- Quick Start
- Simple Example
- Built-in Trust Types
- Custom Trust Types (Optional)
- Permission Patterns
- How It Works
- Trust Relationship Setup
- Migration from Existing Apps
- Common Patterns
- Troubleshooting
- Advanced Topics
- See Also
- ActingWeb Unified Access Control System
- P2P Quickstart
- Trust Manager
- Subscription Manager
- Subscription Processing
- Overview
- Quick Start
- Configuration Options
- Subscription Data Hooks
- Callback Types
- Peer Capability Discovery
- Remote Peer Storage
- Subscription Suspension
- Fan-Out Manager
- Advanced: Component-Level Usage
- Migration from Raw Hooks
- Compatibility
- Error Handling Reference
- Performance Tuning
- Back-Pressure Handling
- Database Support
- See Also
- Property Lists
- ActingWeb Caching Implementation Guide
- Hooks
- Migrating to Async/Await Hooks
- MCP Quickstart
- Building MCP Applications with ActingWeb
- Overview
- Architecture Pattern
- MCP Application Structure
- Key Components
- Quick Start
- Basic MCP Application
- MCP Tools Implementation
- MCP Prompts Implementation
- MCP Resources Implementation
- Property Hooks for MCP Applications
- OAuth2 Integration
- Deployment Patterns
- AWS Lambda with Serverless Framework
- Container Deployment
- Local Development
- Web Interface Customization
- Testing MCP Applications
- Best Practices
- Example: Complete MCP Application
- OAuth2 Client Management
- Web Interface Integration
- Template Integration
- OAuth2ClientManager Interface
- Interface Features
- WWW Handler and Templates
- Overview
- Browser Redirect Behavior
- Web Interface Features
- Dashboard
- Properties Management
- Trust Relationships
- Property Hooks and Web Interface
- Hidden Properties
- Read-Only Properties
- Template System
- Template Location
- Available Templates
- Template URL Variables
- Template Customization
- Static Assets
- Advanced Template Features
- Conditional Content Based on Property Status
- Dynamic Navigation
- Security Considerations
- Property Protection
- Template Security
- Authentication Integration
- URL Structure and Base Paths
- Basic Structure
- With Base Paths (e.g., deployed under /mcp-server)
- Best Practices
- Example: Complete Custom Template
- SPA Mode (Alternative to WWW Handler)
- Related Documentation
- Service Integration
- Database Maintenance Guide
- PostgreSQL Migration Guide
- Logging and Request Correlation
- Troubleshooting
- 401 at /mcp
- DynamoDB Local connection errors
- Slow first request after startup
- Tools/prompts don’t appear in tools/list or prompts/list
- MCP client sees an empty tool list or
-32003after upgrading - MCP tool’s structured data disappeared after upgrading
- MCP client rejects a tool with “has an output schema but did not return structured content”
- Property changes not visible in Web UI
- Subscription Callbacks Not Delivered
- Unexpected Resync Callbacks
- Duplicate Callbacks Being Processed
- Peer Data Not Cleaned Up After Trust Deletion
- Subscriber Returning 429 (Too Many Requests)
- Sequence Gaps Not Resolving
Trust & Relationships
P2P Quickstart - Two actors, one app: establish trust, subscribe, and receive peer data end-to-end
Trust Relationships - Establishing and managing trust between actors
Subscriptions - Event notification system for property changes
Data Management
Property Lists - Working with list-type properties and metadata
Caching - Implementation guide for adding request-scoped caching to endpoints
Hooks - Implementing lifecycle hooks for custom business logic
Async/Await Hooks Migration - Migrating to async hooks for better performance with FastAPI
Integration
MCP Quickstart - Quick start guide for Model Context Protocol integration
MCP Applications - Building AI-accessible applications with MCP
Web UI - Server-rendered web interface templates and SPA mode configuration
Service Integration - Integrating ActingWeb with external services
Operations
Database Maintenance - TTL configuration and cleanup for both DynamoDB and PostgreSQL
PostgreSQL Migration - Complete guide for migrating from DynamoDB to PostgreSQL
Logging and Request Correlation - Request tracing and context-aware logging for debugging
Troubleshooting
Troubleshooting - Common issues and solutions