Auth Concepts

For example, when a user connects their Gmail account to your app, Composio Auth guides the user through Google’s OAuth login. The user securely proves their identity to Google, and Composio safely stores the resulting access token, confirming the user’s identity without you handling sensitive credentials.

On expiry, Composio Auth automatically refreshes the access token, ensuring continuous, secure access without requiring users to re-authenticate.

Continuing the Gmail example, authorization happens when your app attempts to access a user’s inbox. Scopes are used to control what resources a user can access. The application controls access to the resources based on the scopes requested during authentication.

OAuth 2.0 allows users to securely grant limited permissions to your app for accessing their data on third-party services without sharing actual login credentials.

Composio Auth streamlines OAuth by managing user authorization, token handling, secure storage, and token refreshing.

OAuth 2.0 Flow:

API Keys are simple credentials used to directly access services, usually with broad access privileges.

Composio securely stores API keys, automatically applying them to API requests, providing secure yet straightforward access.

API Key Flow:

Bearer Tokens are credentials sent in HTTP headers to securely access protected resources without needing underlying user credentials.

Composio securely manages Bearer Tokens, embedding them in API requests automatically, simplifying secure token handling.

Bearer Token Flow:

Basic Authentication encodes and sends user credentials (username and password) with each request.

Composio securely encodes and handles these credentials, managing headers securely, ensuring sensitive data protection.

Basic Authentication Flow:

JWT is a compact, secure method for encoding user information, claims, and permissions for safe transmission between systems.

Composio manages JWT lifecycle, including creation, validation, verification of signatures, expiration handling, and secure storage.

JWT Flow:

An Integration stores all necessary authentication and API communication details required for making authenticated requests to third-party services. These properties define how Composio interacts with the external API.

Composio supports multiple authentication schemes, and each Integration can define one or more of these:

• Developers configure Integrations once per third-party service.
• Users authenticate against these Integrations to establish personalized connections.
• API calls are routed through Composio, leveraging stored authentication details for seamless execution.

OAuth 2.0 applications generally don’t have any expected_params since the OAuth flow is supposed to capture and store the relevant credentials.

1
from composio_openai import App, ComposioToolSet
2
3
4
toolset = ComposioToolSet()
5
entity = toolset.get_entity("default")
6
github_params = toolset.get_expected_params_for_user(app=App.GITHUB)
7
# []
8
9
github_connection_request = entity.initiate_connection(
10
    app_name=App.GITHUB,
11
    auth_mode=github_params["auth_scheme"],
12
    auth_config={},
13
)
14
print(github_connection_request.model_dump_json(indent=2))

Once the connection object has been created, the redirectUrl has to be emitted back to the user so that they can follow the OAuth credentials.

1
{
2
  "connectionStatus": "INITIATED",
3
  "connectedAccountId": "ec33a9e2-75e1-4e01-9c7a-60a1481e4d8e",
4
  "redirectUrl": "https://backend.composio.dev/s/9eNG2Svq"
5
}

Many applications that have OAuth 2.0, also support the user providing their own Bearer token.

1
from composio_openai import App, ComposioToolSet
2
3
4
toolset = ComposioToolSet()
5
entity = toolset.get_entity("default")
6
gmail_params = toolset.get_expected_params_for_user(app=App.GMAIL, auth_scheme="BEARER_TOKEN")
7
print(gmail_params["expected_params"])
8
# [ExpectedFieldInput(name='token', type='string', description='Token for bearer token auth', displayName='Token', is_secret=False, required=True, expected_from_customer=True, default=None, get_current_user_endpoint=None)]
9
10
11
gmail_connection_request = entity.initiate_connection(
12
  app_name=App.GMAIL,
13
  auth_mode=gmail_params["auth_scheme"],
14
  auth_config={"token": "gmail_token"},
15
)
16
17
print(gmail_connection_request.model_dump_json(indent=2))

1
{
2
  "connectionStatus": "ACTIVE",
3
  "connectedAccountId": "3362dc81-4313-4564-927e-571e4ff51b95",
4
  "redirectUrl": null
5
}

You can ask the user’s to enter in their API key for apps and services that support it. Composio will store the key securely.

1
from composio_openai import App, ComposioToolSet
2
3
toolset = ComposioToolSet()
4
entity = toolset.get_entity("default")
5
6
notion_params = toolset.get_expected_params_for_user(app=App.NOTION)
7
notion_params["expected_params"]
8
print(notion_params["expected_params"])
9
# [ExpectedFieldInput(name='api_key', type='string', description='Your notion API key for authentication. Obtain it from your notion settings.', displayName='API Key', is_secret=False, required=True, expected_from_customer=True, default=None, get_current_user_endpoint=None)]
10
11
notion_connection_request = entity.initiate_connection(
12
    app_name=App.NOTION,
13
    auth_mode=notion_params["auth_scheme"],
14
    auth_config={"token": "notion_token"},
15
)

1
{
2
  "connectionStatus": "ACTIVE",
3
  "connectedAccountId": "da821894-2383-4f75-8590-ebbc242a4129",
4
  "redirectUrl": null
5
}