Composio Authentication Schemes for Connected Accounts: Complete SDK Guide

Composio supports 15 distinct authentication schemes including OAuth 2.0, OAuth 1.0a, API keys, Basic auth, Bearer tokens, SAML, and service accounts, all configurable through the AuthScheme helper in the TypeScript SDK.

The Composio platform enables developers to build integrations with third-party services through Connected Accounts, which require specific authentication schemes to establish secure access. Understanding the available authentication schemes in the Composio SDK is essential for correctly configuring connections to APIs ranging from modern OAuth 2.0 providers to legacy Basic authentication endpoints.

Supported Authentication Schemes in Composio

The Composio SDK defines all supported authentication mechanisms in the AuthSchemeTypes enum located in ts/packages/core/src/types/authConfigs.types.ts. These schemes cover the full spectrum of modern API authentication patterns:

• OAUTH1 – OAuth 1.0a flow for legacy Twitter and other older APIs
• OAUTH2 – OAuth 2.0 flow, the standard for modern SaaS applications
• API_KEY – Simple header or query-parameter based API key authentication
• BASIC – HTTP Basic authentication using username and password
• BEARER_TOKEN – Bearer token authentication, commonly used with JWTs
• BILLCOM_AUTH – Bill.com-specific authentication scheme
• GOOGLE_SERVICE_ACCOUNT – Google service account JSON credentials
• NO_AUTH – No authentication required for public endpoints
• BASIC_WITH_JWT – Basic authentication where the password field contains a JWT
• CALCOM_AUTH – Cal.com-specific authentication scheme
• SERVICE_ACCOUNT – Generic service account credentials for non-Google providers
• SAML – SAML-based Single Sign-On authentication
• DCR_OAUTH – Dynamic Client Registration OAuth flow

Configuring Authentication Schemes in Code

The Composio SDK provides the AuthScheme helper class (implemented in ts/packages/core/src/authScheme.ts) to construct authentication payloads when creating or linking Connected Accounts. This factory ensures type safety and proper formatting for each scheme.

OAuth 2.0 Configuration

OAuth 2.0 is the most commonly used scheme for modern integrations. The following example demonstrates initiating a Connected Account with OAuth 2.0 credentials:

import { Composio, AuthScheme } from '@composio/sdk';

const composio = new Composio({ apiKey: 'YOUR_COMPOSIO_API_KEY' });

const request = await composio.connectedAccounts.initiate(
  'user_123',
  'auth_config_oauth2',
  {
    callbackUrl: 'https://myapp.com/oauth/callback',
    config: AuthScheme.OAuth2({
      access_token: 'access-token',
      token_type: 'Bearer',
      refresh_token: 'refresh-token',
      expires_in: 3600,
    }),
  }
);

console.log('Redirect user to', request.redirectUrl);

API Key Authentication

For services that use simple API keys, use the ApiKey method:

const request = await composio.connectedAccounts.link(
  'user_123',
  'auth_config_api_key',
  {
    config: AuthScheme.ApiKey({ api_key: 'my-secret-key' })
  }
);

await request.waitForConnection();

Basic Authentication

HTTP Basic authentication is supported for legacy systems:

const request = await composio.connectedAccounts.link(
  'user_123',
  'auth_config_basic',
  {
    config: AuthScheme.Basic({ username: 'my-user', password: 'my-pass' })
  }
);

await request.waitForConnection();

Refreshing Credentials

For schemes that support token renewal, use the refresh method:

const refreshed = await composio.connectedAccounts.refresh('conn_abc123');
console.log('New token:', refreshed.credentials?.access_token);

Core Implementation Files

The authentication scheme functionality is distributed across several key files in the Composio TypeScript SDK:

File	Purpose
ts/packages/core/src/types/authConfigs.types.ts	Defines AuthSchemeTypes enum and Zod schemas for validation
ts/packages/core/src/authScheme.ts	Implements the AuthScheme factory helper for constructing auth payloads
ts/packages/core/src/connectedAccounts.ts	Contains runtime logic for initiate, link, and refresh methods
docs/content/reference/sdk-reference/typescript/connected-accounts.mdx	SDK reference documentation for Connected Accounts

Summary

• Composio supports 15 distinct authentication schemes ranging from OAuth 2.0 and SAML to API keys and Basic auth.
• The AuthSchemeTypes enum in ts/packages/core/src/types/authConfigs.types.ts defines all available schemes.
• Use the AuthScheme helper class to construct properly typed authentication payloads when calling connectedAccounts.initiate() or connectedAccounts.link().
• Supported schemes include provider-specific implementations like GOOGLE_SERVICE_ACCOUNT, BILLCOM_AUTH, and CALCOM_AUTH, alongside generic standards.

Frequently Asked Questions

What is the most common authentication scheme used with Composio?

OAuth 2.0 is the most widely used authentication scheme in the Composio ecosystem, as it is the standard for modern SaaS applications. The SDK provides specific support for OAuth 2.0 flows including automatic token refresh handling through the connectedAccounts.refresh() method.

How do I handle authentication for services that don't require credentials?

For public APIs or endpoints that do not require authentication, use the NO_AUTH scheme. When initiating or linking such accounts, you can omit the authentication configuration or explicitly indicate that no credentials are required, allowing the connection to proceed without token validation.

Can I use Composio with Google Workspace service accounts?

Yes, Composio explicitly supports Google service accounts through the GOOGLE_SERVICE_ACCOUNT authentication scheme. This allows you to authenticate using JSON key files from Google Cloud Console, enabling server-to-server interactions with Google Workspace APIs without user intervention.

What is the difference between API_KEY and BEARER_TOKEN schemes?

While both use token-based credentials, the API_KEY scheme typically sends the token via a custom header (like X-API-Key) or query parameter, whereas the BEARER_TOKEN scheme uses the standard Authorization: Bearer <token> header format. Choose API_KEY for proprietary API key implementations and BEARER_TOKEN for OAuth 2.0 or JWT-based access tokens.

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