Connection

Comprehensive guide to connecting and managing third-party applications in Reasoning Stack through secure OAuth, API keys, and custom authentication flows.

Reasoning Stack’s app connection system provides a unified interface for securely connecting to 25+ third-party applications and services. The system handles multiple authentication methods, manages connection states, and provides a streamlined user experience for integrating your digital workspace.

🔗 Connection Overview

The connection system is built around two core components that work together to provide seamless app integration:

App Groups Interface

A dropdown menu that organizes all available integrations by category, showing connection status and providing quick access to connect or disconnect apps.

Connection Dialog

A secure authentication interface that handles different connection types including OAuth flows, API key authentication, and custom authorization methods.

🏗️ Architecture

Connection Categories

Apps are organized into logical categories for better navigation:

Google Workspace

Gmail, Google Drive, Google Docs, Google Sheets, Google Calendar, Google Meet, Google Maps, Google Slides

Communication

Slack, Microsoft Teams, Zoom, Outlook

Social Media

Twitter, LinkedIn, YouTube, Reddit

Productivity

Notion, Confluence, Jira, Miro, Canva, Calendly, HubSpot, Apollo, Klaviyo

SEO & Analytics

Moz, SerpAPI

E-commerce

Shopify

Utilities

TinyURL

Authentication Methods

The system supports multiple authentication approaches:

1. OAuth 2.0 Flow (Composio-based)

Most integrations use OAuth 2.0 through the Composio platform for secure, standardized authentication.

Apps using OAuth:

• All Google Workspace apps (Gmail, Drive, Docs, Sheets, Calendar, Meet, Maps)
• Social media platforms (Twitter, LinkedIn, YouTube, Reddit)
• Communication tools (Slack, Microsoft Teams, Zoom, Outlook)
• Productivity apps (Notion, Confluence, Jira, Calendly, HubSpot, Klaviyo)
• Utilities (TinyURL)

2. Custom OAuth Implementation

Some apps use custom OAuth flows managed directly within the application.

Apps using custom OAuth:

• Miro: Direct OAuth 2.0 integration with Miro’s API

3. API Key Authentication

Certain services require API key authentication for direct integration.

Apps using API keys:

• Apollo: Sales intelligence platform API key
• Shopify: Admin API access token with shop domain

4. Pre-configured Services

Some integrations are pre-configured and don’t require user authentication.

Pre-configured apps:

• Moz: SEO tools (automatically available)
• Canva: Design platform (under development)

🔐 Security Features

OAuth Security

All OAuth flows follow industry-standard security practices with PKCE (Proof Key for Code Exchange) where supported.

• State Parameter Validation: Prevents CSRF attacks during OAuth flows
• Secure Token Storage: Tokens are encrypted and stored securely
• Scope Limitation: Apps only receive the minimum required permissions
• Token Refresh: Automatic token renewal for expired credentials

API Key Protection

• Encrypted Storage: API keys are stored using browser security features
• Input Masking: Sensitive credentials are masked during input
• Secure Transmission: All API communications use HTTPS
• Local Storage: Keys are stored locally, never transmitted to external servers

Permission Management

• Explicit Consent: Users must explicitly approve each connection
• Granular Control: Individual app permissions can be managed
• Easy Disconnection: One-click disconnection from any service
• Audit Trail: Connection history and status tracking

🚀 User Guide

Connecting an App

1. Access Connection Menu

   Click the “Connect Apps” button in the interface to open the connection dropdown menu.

2. Navigate Categories

   Browse through categorized app groups or expand specific categories to find your desired integration.

3. Select Application

   Click on the app you want to connect. The system will automatically determine the appropriate authentication method.

4. Complete Authentication

   Follow the authentication flow specific to your chosen app:

   • OAuth Apps: Redirected to the service’s authorization page
   • API Key Apps: Enter credentials in the secure dialog
5. Confirm Connection

   Once authenticated, the app will show as connected with a green checkmark indicator.

Managing Connections

Viewing Connection Status

• Green Checkmark: Successfully connected and ready to use
• Yellow Warning: App under construction or requires attention
• No Indicator: Not connected or available for connection

Disconnecting Apps

Disconnecting an app will remove all associated permissions and may interrupt ongoing workflows.

1. Locate the connected app in the dropdown menu
2. Click the red “X” button next to the app name
3. Confirm disconnection when prompted
4. The app will immediately be disconnected and marked as available for reconnection

App-Specific Setup

Google Workspace Apps

Most Google services use standard OAuth 2.0 through Composio:

• Click the app name
• Authorize in the Google consent screen
• Grant requested permissions
• Return to Reasoning Stack with active connection

Miro Integration

1. Select Miro

   Choose Miro from the Productivity category.

2. OAuth Authorization

   You’ll be redirected to Miro’s authorization page.

3. Grant Permissions

   Approve board read/write permissions.

4. Return to App

   Complete the OAuth flow and return to Reasoning Stack.

API Key Apps Setup

Apollo Configuration

1. Get API Key

   Visit the Apollo Developer Portal and obtain your API key.

2. Enter Credentials

   Paste your API key in the secure connection dialog.

3. Verify Connection

   The system will validate your credentials and establish the connection.

Shopify Setup

1. Prepare Shop Information

   You’ll need your shop domain (e.g., your-shop.myshopify.com) and Admin API access token.

2. Enter Shop Domain

   Input your complete Shopify shop domain.

3. Add Access Token

   Enter your Admin API access token securely.

4. Confirm Setup

   Both credentials are required for successful Shopify integration.

Storage Mechanisms

• OAuth Tokens: Managed through secure context providers
• API Keys: Stored in encrypted browser localStorage
• Connection Metadata: Tracked in application state
• Session Data: Temporary storage for OAuth flows

Error Handling

The system includes comprehensive error handling:

• Authentication Failures: Clear error messages and retry options
• Network Issues: Automatic retry mechanisms
• Invalid Credentials: Immediate feedback and correction guidance
• Permission Errors: Detailed explanations of required permissions

App-Specific Issues

Google Services

• Scope Conflicts: Ensure you’re granting all requested permissions
• Account Switching: Use the correct Google account for business vs personal use
• Admin Restrictions: Check if your organization allows third-party app connections

Shopify Integration

• Shop Domain Format: Must include .myshopify.com suffix
• API Permissions: Ensure your access token has required scopes
• Store Status: Verify your Shopify store is active and accessible

Social Media Platforms

• Rate Limiting: Be aware of API rate limits for posting and engagement
• Account Verification: Some features require verified accounts
• Privacy Settings: Ensure your account allows third-party access

🔄 Connection Lifecycle

Initial Connection

1. App Selection: User chooses app from categorized menu
2. Authentication: System initiates appropriate auth flow
3. Authorization: User grants permissions on service platform
4. Token Exchange: System securely exchanges auth codes for tokens
5. Storage: Credentials are encrypted and stored securely
6. Validation: Connection is tested and marked as active

Ongoing Management

• Token Refresh: Automatic renewal of expired tokens
• Health Checks: Periodic validation of connection status
• Permission Updates: Handling of changed app permissions

Disconnection Process

1. User Initiation: User clicks disconnect button
2. Token Revocation: System revokes tokens on service platform
3. Local Cleanup: All stored credentials are removed
4. State Update: Connection status is updated immediately
5. Notification: User receives confirmation of disconnection

The app connection system in Reasoning Stack provides a robust, secure, and user-friendly way to integrate your entire digital workspace into a unified AI-powered platform. Whether you’re connecting through OAuth, API keys, or custom flows, the system ensures your data remains secure while providing seamless access to all your favorite applications.