How to Handle Authentication and OAuth Flows in Claude App Automation Skills

Claude app automation skills use Composio's Tool Router to manage OAuth flows automatically, storing tokens persistently and refreshing them via the RUBE_MANAGE_CONNECTIONS tool when authentication expires.

When building automation skills for Claude that interact with external services like Gmail, Slack, or Zoho Mail, handling authentication securely is critical. The ComposioHQ/awesome-claude-skills repository provides a standardized architecture that abstracts OAuth complexity away from skill developers. This guide explains how the authentication system works based on the actual implementation in the Connect and Connect-Apps skills.

Understanding the OAuth Architecture

The authentication system relies on a centralized design where Composio's backend manages token storage and refresh while Claude handles user interaction.

The Tool Router Pattern

At the core of every skill is Composio's Tool Router, which intercepts API calls requiring authentication. When Claude attempts an action against a third-party app with no active connection, the router returns a standardized OAuth authorization request rather than failing. This pattern is documented in connect/SKILL.md【/cache/repos/github.com/ComposioHQ/awesome-claude-skills/master/connect/SKILL.md#L119-L126】, where the Auth Flow section specifies that Claude must present the OAuth link to the user when encountering unauthenticated requests.

MCP Configuration

The Multi-Connection Provider (MCP) configuration stored in ~/.mcp.json tells Claude how to reach Composio's backend. According to connect-apps-plugin/commands/setup.md【/cache/repos/github.com/ComposioHQ/awesome-claude-skills/master/connect-apps-plugin/commands/setup.md#L15-L27】, the setup command automatically writes this configuration file, including the API key required to authenticate requests to the Tool Router.

Implementing the OAuth Flow

The authentication process follows five standardized steps that persist across conversation sessions.

1. First-time detection – When Claude receives a request requiring external app access (e.g., "send a Slack message"), the Tool Router checks for an existing connection. If none exists, it returns an OAuth authorization link to the user interface【/cache/repos/github.com/ComposioHQ/awesome-claude-skills/master/connect-apps/SKILL.md#L57-L63】.

2. User authorization – The user clicks the provided link, completes the OAuth consent screen on the provider's site, and confirms by telling Claude "connected".

3. Token persistence – Composio stores the access and refresh tokens in a connection record tied to the user ID. Subsequent API calls automatically inject these tokens without user intervention.

4. Automatic reuse – Future requests to the same app use the stored connection. The Quick Start guide in connect-apps/SKILL.md【/cache/repos/github.com/ComposioHQ/awesome-claude-skills/master/connect-apps/SKILL.md#L57-L63】 notes that after the initial setup, users simply describe the action they want without mentioning authentication.

5. Failure recovery – If a token expires or is revoked, the skill automatically detects authentication errors and re-initiates the OAuth flow.

Managing Connection Lifecycle with RUBE_MANAGE_CONNECTIONS

Service-specific skills handle token expiration using the RUBE_MANAGE_CONNECTIONS tool. This utility manages the connection lifecycle—creating new connections, refreshing expired tokens, and re-running OAuth when necessary.

In composio-skills/zoho_mail-automation/SKILL.md【/cache/repos/github.com/ComposioHQ/awesome-claude-skills/master/composio-skills/zoho_mail-automation/SKILL.md#L24-L27】【/cache/repos/github.com/ComposioHQ/awesome-claude-skills/master/composio-skills/zoho_mail-automation/SKILL.md#L94-L99】, the implementation checks connection status before executing actions. If the status is not ACTIVE, the skill calls RUBE_MANAGE_CONNECTIONS to refresh credentials before proceeding. This ensures automation scripts don't fail mid-execution due to expired sessions.

Code Implementation Examples

Setting Up the MCP Client

The following Python implementation from connect/SKILL.md【/cache/repos/github.com/ComposioHQ/awesome-claude-skills/master/connect/SKILL.md#L95-L113】 demonstrates how to initialize Claude with Composio authentication support:

from composio import Composio
from claude_agent_sdk.client import ClaudeSDKClient
from claude_agent_sdk.types import ClaudeAgentOptions
import os

composio = Composio(api_key=os.environ["COMPOSIO_API_KEY"])
session = composio.create(user_id="user_123")

options = ClaudeAgentOptions(
    system_prompt="You can take actions in external apps.",
    mcp_servers={
        "composio": {
            "type": "http",
            "url": session.mcp.url,
            "headers": {"x-api-key": os.environ["COMPOSIO_API_KEY"]},
        }
    },
)

async with ClaudeSDKClient(options) as client:
    await client.query("Send Slack message to #general: Hello!")

Handling Re-authentication

When automating Zoho Mail operations, the skill checks connection status before listing folders. If authentication fails, it triggers the re-authentication flow automatically:

# Initial request attempts to use existing connection

await client.query("List Zoho Mail folders")

# If connection is not ACTIVE, Claude prompts for re-authentication

# which internally invokes RUBE_MANAGE_CONNECTIONS

await client.query("Re-authenticate Zoho Mail")

Summary

• Standardized OAuth – The ComposioHQ/awesome-claude-skills repository uses a centralized Tool Router to handle OAuth flows uniformly across all external services.
• Persistent connections – Tokens are stored per-user in Composio's backend and automatically reused, requiring only one authorization prompt per service.
• Automatic refresh – The RUBE_MANAGE_CONNECTIONS tool handles token expiration transparently, as shown in service-specific implementations like Zoho Mail.
• MCP configuration – The ~/.mcp.json file configures the connection to Composio's backend, created automatically by the Connect-Apps setup command.

Frequently Asked Questions

How does Claude know when to prompt for OAuth?

Claude detects unauthenticated requests through the Composio Tool Router. When attempting an action against an app without an active connection, the router returns a specific response code indicating authentication is required, triggering Claude to present the OAuth link to the user【/cache/repos/github.com/ComposioHQ/awesome-claude-skills/master/connect/SKILL.md#L119-L126】.

Where are OAuth tokens stored?

Tokens are stored in Composio's secure connection store, associated with the specific user ID provided during session creation. The skill references these tokens via the MCP server configuration without exposing them in Claude's context window or local storage.

What happens when an OAuth token expires?

When a request fails with an authentication error, skills automatically invoke the RUBE_MANAGE_CONNECTIONS tool to refresh the token or initiate a new OAuth flow. This pattern is implemented in zoho_mail-automation/SKILL.md【/cache/repos/github.com/ComposioHQ/awesome-claude-skills/master/composio-skills/zoho_mail-automation/SKILL.md#L94-L99】, where connections are validated before every action.

Can I use the same authentication across multiple Claude sessions?

Yes. Because Composio stores tokens in a persistent connection record tied to the user ID, subsequent sessions initialized with the same user ID will reuse existing valid connections. The MCP configuration in ~/.mcp.json persists across sessions, maintaining the link to Composio's backend.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}