Skip to content

Architecture

Coherence is designed with security and privacy at its core. All data is encrypted at rest and in transit, conversations are strictly isolated by app and user, and authentication credentials are never stored persistently. Our SOC 2 Type II certification and GDPR compliance ensure enterprise-grade security for your chat integration. The architecture supports both OAuth-based authentication for seamless frontend-only integration and Backend SDK mode for custom authentication requirements, giving you flexibility while maintaining the highest security standards.

Overview

Coherence offers two primary integration modes, each optimized for different authentication scenarios:

OAuth Mode - Frontend-Only Integration

Perfect for applications with OAuth/OIDC authentication, this mode requires no backend changes:

┌─────────────────┐     ┌─────────────────┐
│   Your Users    │────▶│ Your Frontend   │
└─────────────────┘     └─────────────────┘
                               │
                               │ Coherence SDK + OAuth Token
                               ▼
                        ┌─────────────────┐
                        │ Coherence       │
                        │ Frontend SDK    │
                        └─────────────────┘
                               │
                               │ Direct Auth + SSE Stream
                               ▼
                        ┌─────────────────────────────────┐
                        │    Coherence Backend            │
                        │  - OAuth Token Validation       │
                        │  - JWT Generation               │
                        │  - Conversation Storage         │
                        │  - Agent Orchestration          │
                        │  - MCP Tool Execution           │
                        └─────────────────────────────────┘
                                       │
                                       │ MCP Protocol
                                       ▼
                        ┌─────────────────────────────────┐
                        │    Generated MCP Server         │
                        │  - Your API Integration         │
                        │  - Tool Definitions             │
                        │  - Auth Forwarding             │
                        └─────────────────────────────────┘
                                       │
                                       │ API Calls with User Auth
                                       ▼
                        ┌─────────────────────────────────┐
                        │    Your Existing APIs           │
                        │  - Business Logic               │
                        │  - Data Access                  │
                        │  - Permissions                  │
                        └─────────────────────────────────┘

OAuth Authentication Flow:

  1. User loads your app with existing OAuth session
  2. Coherence SDK sends OAuth token to Coherence Backend
  3. Backend validates token against your JWKS/JWT secret
  4. Coherence Backend issues conversation-scoped JWT to SDK
  5. SDK uses JWT for all subsequent requests
  6. Messages stream directly between SDK and Coherence Backend

Backend SDK Mode - Custom Authentication

Ideal for custom authentication systems or when you need additional control:

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Your Users    │────▶│ Your Frontend   │────▶│  Your Backend   │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                               │                          │
                               │ Coherence SDK            │ Auth + Messages
                               ▼                          ▼
                        ┌─────────────────┐     ┌─────────────────┐
                        │ Coherence       │◀────│ Coherence       │
                        │ Frontend SDK    │     │ Backend SDK     │
                        └─────────────────┘     └─────────────────┘
                               │                          │
                               │ SSE Stream               │ API Key Auth
                               ▼                          ▼
                        ┌─────────────────────────────────┐
                        │    Coherence Backend            │
                        │  - API Key Validation           │
                        │  - JWT Generation               │
                        │  - Conversation Storage         │
                        │  - Agent Orchestration          │
                        │  - MCP Tool Execution           │
                        └─────────────────────────────────┘
                                       │
                                       │ MCP Protocol
                                       ▼
                        ┌─────────────────────────────────┐
                        │    Generated MCP Server         │
                        │  - Your API Integration         │
                        │  - Tool Definitions             │
                        │  - Auth Forwarding             │
                        └─────────────────────────────────┘
                                       │
                                       │ API Calls with User Auth
                                       ▼
                        ┌─────────────────────────────────┐
                        │    Your Existing APIs           │
                        │  - Business Logic               │
                        │  - Data Access                  │
                        │  - Permissions                  │
                        └─────────────────────────────────┘

Backend SDK Authentication Flow:

  1. User loads your app with your existing auth
  2. Frontend requests chat token from your backend
  3. Your backend uses Coherence SDK with API key
  4. SDK generates user-scoped JWT via Coherence Backend
  5. Your backend returns JWT to frontend
  6. Frontend SDK uses JWT for all requests
  7. Messages can be sent via your backend or directly

Component Details

Your Application

  • Your Frontend: Hosts Coherence SDK, manages auth, renders chat UI
  • Your Backend: provides APIs/endpoints for MCP to access data
  • Your Backend (Backend SDK mode): Integrates Backend SDK, provides chat endpoint (one small route), forwards credentials securely,

Coherence SDKs

  • Frontend SDK: Lightweight bundle (~50KB), framework-agnostic, manages conversation state/UI, real-time streaming, multimodal support
  • Backend SDK: Node.js/Python/Ruby/Go, secure token generation, auth forwarding, minimal overhead (~5ms)

Coherence Backend

Our hosted service that handles all the heavy lifting:

  • Authentication: JWT generation/validation, API key management, OAuth verification, per-conversation access control
  • Conversation Engine: Message storage/retrieval, threading, file attachments, search/analytics
  • Agent Runtime: LangGraph ReAct agent or Deep Research Agent, MCP tool orchestration, context management, response streaming
  • Infrastructure: Global Google Cloud deployment, Redis event streaming, PostgreSQL storage, S3-compatible attachments
  • MCP Server Hosting: We host the MCP servers and manage their authentication integrations, both for your own APIs as well as 3rd party MCP servers

MCP Server

We automatically generate and host an MCP (Model Context Protocol) server for your API. This is the exclusive method for connecting your data to chat agents.

First-Party MCP Generation

Auto-generated from your API specification with secure credential forwarding, request/response transformation, error handling and retries, rate limiting and caching.

Integration methods: OpenAPI import, GitHub auto-sync, or manual configuration through our dashboard.

Third-Party MCP Integration Separate setup process for existing MCP servers (Stripe, Salesforce, Linear, etc.). Each service requires individual configuration in the dashboard but can be combined with your first-party MCP in the same agent.

Message Flow

OAuth Mode Message Flow

  1. User sends message via UI
  2. SDK posts directly to Coherence with JWT + auth info
  3. Coherence validates OAuth-based JWT
  4. Agent processes message and calls tools
  5. MCP server executes API calls with forwarded auth
  6. Responses stream back via SSE
  7. SDK updates UI in real-time

Backend SDK Message Flow

  1. User sends message via UI

  2. SDK can either:

  3. Post to your backend, which forwards to Coherence

  4. Post directly to Coherence with JWT
  5. Coherence validates API key or JWT
  6. Agent processes message and calls tools
  7. MCP server executes API calls with forwarded auth
  8. Responses stream back via SSE
  9. SDK updates UI in real-time

Security & Privacy Details

  • Data Isolation: App+user scoped conversations, no cross-tenant access, encryption at rest/transit
  • Authentication Security: Short-lived JWTs (1hr), API keys never frontend-exposed, existing auth system support
  • Credential Handling: Single-request auth info usage, never stored persistently, secure MCP forwarding
  • Compliance: SOC 2 Type II (Q3 2025), GDPR compliant, data residency options

Choosing Your Integration Mode

  • OAuth Mode: OAuth/OIDC auth, frontend-only integration, easiest setup
  • Backend SDK Mode: Custom auth, additional validation, audit trails, request transformation
  • Hybrid: Use both modes simultaneously for different user types with unified experience

Next Steps