> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reasoningstack.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

<CardGroup cols={2}>
  <Card title="Google Workspace" icon="google">
    Gmail, Google Drive, Google Docs, Google Sheets, Google Calendar, Google Meet, Google Maps, Google Slides
  </Card>

  <Card title="Communication" icon="message-circle">
    Slack, Microsoft Teams, Zoom, Outlook
  </Card>

  <Card title="Social Media" icon="share-2">
    Twitter, LinkedIn, YouTube, Reddit
  </Card>

  <Card title="Productivity" icon="zap">
    Notion, Confluence, Jira, Miro, Canva, Calendly, HubSpot, Apollo, Klaviyo
  </Card>

  <Card title="SEO & Analytics" icon="trending-up">
    Moz, SerpAPI
  </Card>

  <Card title="E-commerce" icon="shopping-cart">
    Shopify
  </Card>

  <Card title="Utilities" icon="link">
    TinyURL
  </Card>
</CardGroup>

### 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

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

* **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

<Steps>
  <Step title="Access Connection Menu">
    Click the "Connect Apps" button in the interface to open the connection dropdown menu.
  </Step>

  <Step title="Navigate Categories">
    Browse through categorized app groups or expand specific categories to find your desired integration.
  </Step>

  <Step title="Select Application">
    Click on the app you want to connect. The system will automatically determine the appropriate authentication method.
  </Step>

  <Step title="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
  </Step>

  <Step title="Confirm Connection">
    Once authenticated, the app will show as connected with a green checkmark indicator.
  </Step>
</Steps>

### 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

<Warning>
  Disconnecting an app will remove all associated permissions and may interrupt ongoing workflows.
</Warning>

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

<Steps>
  <Step title="Select Miro">
    Choose Miro from the Productivity category.
  </Step>

  <Step title="OAuth Authorization">
    You'll be redirected to Miro's authorization page.
  </Step>

  <Step title="Grant Permissions">
    Approve board read/write permissions.
  </Step>

  <Step title="Return to App">
    Complete the OAuth flow and return to Reasoning Stack.
  </Step>
</Steps>

#### API Key Apps Setup

##### Apollo Configuration

<Steps>
  <Step title="Get API Key">
    Visit the [Apollo Developer Portal](https://developer.apollo.io/) and obtain your API key.
  </Step>

  <Step title="Enter Credentials">
    Paste your API key in the secure connection dialog.
  </Step>

  <Step title="Verify Connection">
    The system will validate your credentials and establish the connection.
  </Step>
</Steps>

##### Shopify Setup

<Steps>
  <Step title="Prepare Shop Information">
    You'll need your shop domain (e.g., `your-shop.myshopify.com`) and Admin API access token.
  </Step>

  <Step title="Enter Shop Domain">
    Input your complete Shopify shop domain.
  </Step>

  <Step title="Add Access Token">
    Enter your Admin API access token securely.
  </Step>

  <Step title="Confirm Setup">
    Both credentials are required for successful Shopify integration.
  </Step>
</Steps>

### 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.