Skip to content

Third-Party App Integrations

This document details how AngelCX integrates with third-party applications through OAuth2 authentication and manages these integrations across different services.

Integration Flow Overview

sequenceDiagram participant AD as Admin Dashboard participant AA as Admin API participant DB as Database participant TP as Third Party Service participant AI as AI Tools AD->>DB: 1. Fetch available apps DB-->>AD: Return app list AD->>AA: 2. Initiate OAuth AA->>TP: 3. Request auth URL TP-->>AA: Return auth URL AA-->>AD: Return auth URL AD->>TP: 4. Redirect to auth TP->>AD: 5. Redirect with code AD->>AA: 6. Send auth code AA->>TP: 7. Exchange for tokens TP-->>AA: Return tokens AA->>DB: 8. Store OAuth tokens AA-->>AD: Confirm connection Note over AI: Later usage AI->>DB: 9. Fetch tokens DB-->>AI: Return tokens AI->>TP: 10. Make API calls

Database Schema

For a detailed description of the third_party_oauth table and other integration-related database tables, see the Database Overview documentation.

Integration Process

1. Available Apps Discovery

  1. Admin Dashboard queries the database for available integrations: sql SELECT * FROM third_party_app WHERE is_coming_soon = false;
  2. The UI displays each app with its icon, name, and description
  3. Apps marked as is_coming_soon = true are shown with a "Coming Soon" badge

2. Connection Flow

When a user initiates a connection:

  1. Initiate OAuth

    • Admin Dashboard calls Admin API endpoint (e.g., /api/third-party-apps/{slug}/authorize)
    • Admin API generates state token and constructs authorization URL
    • Returns URL to Admin Dashboard

  2. Authorization

    • User is redirected to third-party service's authorization page
    • User grants necessary permissions
    • Service redirects back to Admin Dashboard with temporary code

  3. Token Exchange

    • Admin Dashboard sends code to Admin API
    • Admin API exchanges code for access and refresh tokens
    • Tokens are stored in third_party_oauth table:

    sql INSERT INTO third_party_oauth ( access_token, refresh_token, expiry, third_party_app_id, agent_id, additional_data ) VALUES (...);

3. Usage in Services

AI Engine Integration

The AI Engine uses these integrations to provide real-time capabilities to AI agents:

  1. Token Retrieval

  2. API Calls

    • AI Engine uses tokens to make authenticated requests to third-party services
    • Responses are processed and used in agent conversations

Post-Session Processing

The Post-Session service handles automated tasks after conversations end:

  1. Task Execution

    • Service checks for relevant integrations
    • Retrieves OAuth tokens
    • Executes configured actions (e.g., creating HubSpot contacts)

  2. Error Handling

    • Failed tasks are retried with exponential backoff
    • Token refresh is handled automatically when needed

Security Considerations

  1. Token Storage

    • Access and refresh tokens are encrypted at rest
    • Tokens are never logged or exposed in error messages

  2. Token Refresh

    • Automatic refresh of expired access tokens
    • Refresh tokens are rotated when possible
    • Failed refreshes trigger admin notifications

  3. Access Control

    • OAuth tokens are scoped to specific agents
    • Regular audit of token usage and permissions

Token Encryption Implementation Plan

The current implementation will be enhanced with stronger encryption for OAuth tokens using Python's cryptography library. For detailed technical specifications and implementation timeline, see our Token Security Enhancement Plan.

Planned Improvements

  1. Encryption at Rest

    • Implement Fernet (symmetric encryption) for token storage
    • Use a separate key management service (Secret Manager) for encryption keys
    • Rotate encryption keys periodically

  2. Database Changes

    • Modify third_party_oauth table to store encrypted tokens
    • Add key version tracking for rotation management
    • Implement automatic re-encryption during key rotation

  3. Security Measures

    • Encryption keys stored separately from data
    • Regular key rotation (every 30 days)

  4. Decryption During Usage

    • When AI Tools or Post-Session services need to access tokens, they retrieve encrypted tokens from the database
    • Tokens are decrypted in-memory using the current encryption key before making API calls
    • Decrypted tokens are never persisted or logged