OAuth Integration Deep Dive

What You'll Learn

This tutorial explores real OAuth implementation patterns from a production email agent application:

• OAuth Configuration: Multi-provider setup in app_manifest.yaml with proper scopes and parameters
• Credential Service: Frontend OAuth flow handling with CredentialService class
• Connection Management: Building UI components for OAuth connections
• Agent Integration: Using OAuth credentials in Python agents with the execute() pattern
• Multi-Provider Support: Unified abstraction for Gmail, Outlook, and Yahoo
• Error Handling: Production-ready error recovery and token refresh

Step 1: OAuth Architecture Overview

Fiberwise provides a complete OAuth infrastructure. Here's how the pieces fit together:

Step 2: OAuth Configuration in app_manifest.yaml

The app manifest is where you define OAuth authenticators. Here's the real configuration from the email-agent-app:

# app_manifest.yaml - OAuth configuration section
oauth:
  authenticators:
    - name: Gmail
      type: oauth2
      file: .fiber/local/oauth/fiberwise_developer.json
      scopes:
        - openid
        - profile
        - email
        - https://www.googleapis.com/auth/gmail.readonly
        - https://www.googleapis.com/auth/gmail.send
      additional_params:
        access_type: offline    # Request refresh token
        prompt: consent         # Always show consent screen

Agent Permissions for OAuth

Your agent must declare OAuth permissions in the manifest:

# Agent section of app_manifest.yaml
agents:
  - name: email-agent
    implementation_path: agents/email_agent.py
    language: python
    agent_type_id: custom
    description: Agent for working with emails across different providers using OAuth
    permissions:
      - credentials.oauth    # Required for OAuth operations
      - data.read
      - data.write
      - llm.completion
    allowed_context_variables:
      - user_id
      - app_id
      - provider_id
      - template_name

{
  "client_id": "YOUR_OAUTH_CLIENT_ID",
  "client_secret": "YOUR_OAUTH_CLIENT_SECRET",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token"
}

Step 3: The CredentialService Class

The CredentialService handles all OAuth operations on the frontend. Here's the real implementation:

/**
 * FiberWise Credential Service
 * Provides functionality for OAuth authentication and credential management
 */

class CredentialService {
  /**
   * Create a new Credential Service client
   * @param {Object} options - Configuration options
   * @param {FiberwiseAppConfig} options.config - Simple configuration instance
   * @param {string} options.appId - Optional app ID to override config
   * @param {string} options.baseUrl - Optional API base URL
   */
  constructor(options = {}) {
    this.config = options.config;
    this.appId = options.appId;
    this.baseUrl = options.baseUrl || 'https://api.fiberwise.ai/api/v1';
    this.credentialsBasePath = '/credentials';
  }

  /**
   * Get the app ID for this instance
   * @returns {string} - App ID from options or config
   */
  getAppId() {
    return this.appId || (this.config && this.config.get('appId'));
  }

  /**
   * Get headers for API requests
   * @returns {Object} - Headers object
   */
  getHeaders() {
    const headers = {
      'Content-Type': 'application/json'
    };

    // Add API key if available
    const apiKey = this.config && this.config.get('apiKey');
    if (apiKey) {
      headers['X-API-Key'] = apiKey;
    }

    return headers;
  }

  /**
   * Get the full URL to initiate OAuth authentication for a provider
   * @param {string} providerId - The provider ID to authenticate with
   * @param {Object} options - Additional options
   * @param {string} options.returnTo - Path to return to after authentication
   * @returns {string} - Full URL to initiate authentication
   */
  getAuthUrl(providerId, options = {}) {
    if (!providerId) {
      throw new Error('Provider ID is required');
    }

    const appId = this.getAppId();
    const queryParams = new URLSearchParams();

    // Add return path if available
    if (options.returnTo) {
      queryParams.set('return_to', options.returnTo);
    }

    // Add app ID if available
    if (appId) {
      queryParams.set('app_id', appId);
    }

    // Build the full URL with query parameters
    const queryString = queryParams.toString() ? `?${queryParams.toString()}` : '';
    return `${this.baseUrl}${this.credentialsBasePath}/auth/initiate/${providerId}${queryString}`;
  }

  /**
   * Initiate OAuth authentication with a provider (redirects browser)
   * @param {string} providerId - The provider ID to authenticate with
   * @param {Object} options - Additional options
   * @param {string} options.returnTo - Path to return to after authentication
   * @returns {Promise} - Redirects the browser
   */
  initiateAuth(providerId, options = {}) {
    try {
      const authUrl = this.getAuthUrl(providerId, options);
      // Use AppBridge router for navigation instead of direct window.location
      if (window.FIBER?._appBridge?._router) {
        window.FIBER._appBridge._router.navigateTo(authUrl);
      } else {
        console.error('AppBridge router not available for OAuth navigation');
        throw new Error('Router not available for OAuth flow');
      }
      return Promise.resolve();
    } catch (error) {
      return Promise.reject(error);
    }
  }

  /**
   * List all OAuth connections for the current user
   * @param {Object} options - List options
   * @param {string} options.appId - Optional app ID to filter connections
   * @returns {Promise} - List of connections
   */
  async listConnections(options = {}) {
    try {
      // Get app ID from options or from instance
      const appId = options.appId || this.getAppId();

      // Build query parameters
      const queryParams = new URLSearchParams();
      if (appId) {
        queryParams.set('app_id', appId);
      }

      const queryString = queryParams.toString() ? `?${queryParams.toString()}` : '';

      // Use the service providers endpoint
      const response = await fetch(
        `${this.baseUrl}/apps/${appId}/service-providers${queryString}`,
        {
          method: 'GET',
          headers: this.getHeaders(),
          credentials: 'include'
        }
      );

      if (!response.ok) {
        throw new Error(`Failed to list connections: ${response.statusText}`);
      }

      const providers = await response.json();

      // Filter to only return actually connected providers
      return (providers || []).filter(provider => Boolean(provider.is_connected));
    } catch (error) {
      console.error('Error listing connections:', error);
      return [];
    }
  }

  /**
   * Revoke an OAuth connection
   * @param {string} connectionId - The connection ID to revoke
   * @param {Object} options - Additional options
   * @param {string} options.appId - Optional app ID context
   * @returns {Promise