OAuth API

Complete reference for OAuth integration including authentication flows and token management.

OAuth Provider Management

Manage OAuth providers for secure third-party API integrations.

Register OAuth Provider

POST /api/v1/credentials/oauth/register

Request Body

{
  "provider_name": "gmail",
  "client_id": "123456-abc.apps.googleusercontent.com",
  "client_secret": "GOCSPX-your_secret_here",
  "redirect_uri": "http://localhost:7001/api/v1/credentials/auth/callback/gmail",
  "token_data": {
    "authorize_url": "https://accounts.google.com/o/oauth2/auth",
    "token_url": "https://oauth2.googleapis.com/token",
    "scopes": ["https://www.googleapis.com/auth/gmail.readonly"]
  }
}

Response

{
  "success": true,
  "provider_id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "OAuth provider registered successfully"
}

Start OAuth Flow

GET /api/v1/credentials/auth/{provider_name}

Query Parameters

Parameter Type Description
return_to string Path to redirect after authentication
app_id UUID Optional application context

Example

GET /api/v1/credentials/auth/gmail?return_to=/dashboard&app_id=123e4567-e89b-12d3-a456-426614174000

This endpoint redirects to the OAuth provider's authorization page.

OAuth Callback

GET /api/v1/credentials/auth/callback/{provider_name}

Handles the OAuth callback from the provider. This endpoint:

  • Validates the state parameter for CSRF protection
  • Exchanges authorization code for access tokens
  • Stores tokens securely in the database
  • Redirects to the original return URL

List OAuth Connections

GET /api/v1/credentials/oauth/connections

Response

[
  {
    "provider_type": "gmail",
    "app_id": "123e4567-e89b-12d3-a456-426614174000",
    "created_at": "2025-01-10T15:30:00Z",
    "status": "active"
  }
]

Revoke OAuth Connection

DELETE /api/v1/credentials/oauth/connections/{provider_name}

Response

{
  "success": true,
  "message": "OAuth connection revoked successfully"
}

CLI Commands

Manage OAuth providers through the Fiberwise CLI.

Account-Level OAuth

Configure Provider

fiber account oauth configure gmail \
  --client-id "your-client-id" \
  --client-secret "your-client-secret" \
  --redirect-uri "http://localhost:7001/api/v1/credentials/auth/callback/gmail" \
  --scopes "https://www.googleapis.com/auth/gmail.readonly"

List Providers

fiber account oauth list-providers

Start OAuth Flow

fiber account oauth auth gmail --config-name myinstance

List Connections

fiber account oauth list-connections --config-name myinstance

Revoke Connection

fiber account oauth revoke gmail --config-name myinstance

App-Level OAuth

Register Provider

fiber app oauth register --provider-config gmail-config.json

List Providers

fiber app oauth list-providers

Delete Provider

fiber app oauth delete-provider provider-id

Security Features

🛡️ CSRF Protection

  • State parameter validation
  • Session binding
  • Request origin verification

🔐 Token Security

  • Encrypted token storage
  • Automatic refresh handling
  • Secure key rotation
  • Expiration management

🎯 Access Control

  • User-scoped token access
  • App-context isolation
  • API key authentication
  • Granular scope management

Integration Examples

Python Agent

from fiberwise_sdk import FiberAgent

class EmailAgent(FiberAgent):
    def __init__(self):
        super().__init__()
        self.oauth = self.get_oauth_provider()

    def process(self, input_data):
        # Get Gmail credentials
        gmail_creds = self.oauth.get_credentials("gmail")

        if not gmail_creds:
            return {"error": "Gmail not authenticated"}

        # Use credentials with Gmail API
        import googleapiclient.discovery
        service = googleapiclient.discovery.build(
            'gmail', 'v1', credentials=gmail_creds
        )

        # List recent emails
        results = service.users().messages().list(
            userId='me', maxResults=10
        ).execute()

        return {
            "message_count": len(results.get('messages', [])),
            "authenticated": True
        }

Node.js Agent

const { FiberAgent } = require('@fiberwise/sdk');

class EmailAgent extends FiberAgent {
    constructor() {
        super();
        this.oauth = this.getOAuthProvider();
    }

    async process(inputData) {
        // Get Gmail credentials
        const gmailCreds = await this.oauth.getCredentials('gmail');

        if (!gmailCreds) {
            return { error: 'Gmail not authenticated' };
        }

        // Use credentials with Gmail API
        const { google } = require('googleapis');
        const gmail = google.gmail({ version: 'v1', auth: gmailCreds });

        const response = await gmail.users.messages.list({
            userId: 'me',
            maxResults: 10
        });

        return {
            messageCount: response.data.messages?.length || 0,
            authenticated: true
        };
    }
}

Next Steps

Ready to implement OAuth in your applications?

OAuth Setup Guide Email Processing Tutorial OAuth Concepts