STIP Core Gateway API
Central orchestration layer for conversational AI systems
STIP Core Gateway API
Welcome to the documentation for the STIP Core Gateway API — the central hub for managing users, agents, channels, conversations, and authorization in the STIP Core conversational system.
What is STIP Core Gateway API?
The Gateway API is the orchestration layer that connects multiple components of the STIP Core system:
- User & Tenant Management: User authentication and multi-tenant isolation
- Agent Management: Configuration and lifecycle management of conversational agents
- Channel Management: Support for multiple input channels (chat, voice, email, SIP)
- Conversation Management: Initialize conversations and manage state
- Authorization: OAuth2 and Machine-to-Machine (M2M) authentication
Who is this for?
- Backend Engineers: Building integrations with the Gateway API
- DevOps/Infrastructure Teams: Deploying and configuring the service
- API Consumers: External systems that need to communicate with STIP Core
- Maintainers: Contributing to the Gateway codebase
System Architecture
┌─────────────────────────────────────────────────────────┐
│ STIP Core System │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ Gateway API (This Repository) │ │
│ │ - User Management │ │
│ │ - Agent Configuration │ │
│ │ - Channel Management │ │
│ │ - Conversation Initialization │ │
│ │ - OAuth2 & M2M Authentication │ │
│ └──────────────────────────────────────────────────┘ │
│ ↕ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ Agents API KB API │ │
│ │ (State & LLM Responses) (Knowledge Base) │ │
│ │ ↕ ↕ │ │
│ │ Livekit Agent External Systems │ │
│ │ (Voice/STT/TTS/SIP) (Webhooks) │ │
│ └─────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────┘Key Features
🔐 Multi-Layer Authentication
- OAuth2 for user-facing operations
- M2M Authentication for system-to-system communication
- Extensible provider architecture (Cognito, Azure AD, Google Cloud)
💬 Conversation Management
- JWT-based conversation tokens with RSA256 signing
- 8-hour token validity with optional key rotation
- Complete agent configuration embedded in tokens
🪝 Webhook System
- onStart: Synchronous context injection
- onMessage: Asynchronous interaction logging
- onEnd: Final analytics and conversation summary
📡 Multi-Channel Support
- Chat, Voice (SIP), Email, Livekit integration
- Channel availability and scheduling
- Channel-specific context routing
🏢 Multi-Tenant Architecture
- Complete tenant isolation
- Tenant-specific configuration keys
- Resource quotas and permissions
Documentation Sections
Quick Start
Get up and running locally in minutes. Includes setup, environment configuration, and first API call.
Architecture
Deep dive into system design, component interactions, and data flows.
Guides
- Authentication & Authorization
- Conversation Management & JWT
- Webhook Integration
API Reference
Complete API structure, router organization, and service patterns.
Changelog
Notable changes, versions, and migration notes.
Technology Stack
- Framework: FastAPI (Python 3.10+)
- Database: PostgreSQL (main + KB)
- Cache: Redis
- Authentication: JWT + OAuth2
- Security: RSA256 signing, HMAC validation
- Monitoring: Sentry, Langfuse
Quick Links
Next Steps
- New to STIP Core? Start with Quick Start
- Need to understand the architecture? See Architecture Overview
- Integrating external systems? Check Webhook Integration
- Building on the API? Review API Reference
Questions? Refer to the relevant section or check the codebase at /app