> ## Documentation Index
> Fetch the complete documentation index at: https://composio-preview.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Importing existing connections

> Pass existing API keys, bearer tokens, or other credentials into Composio so your users don't need to re-authenticate

If your users have already authenticated with a service and you have their credentials (API keys, bearer tokens, etc.), you can pass those directly into Composio. No re-authentication required.

This is useful when:

* Your app already stores API keys or tokens for users
* You're adopting Composio and want to onboard existing users without disrupting them
* You want to use bearer tokens with OAuth toolkits (Gmail, GitHub, Slack, etc.) without setting up an OAuth app

## How it works

connection.import
no re-authentication

## Prerequisites

1. **An [auth config](https://composio-preview.mintlify.site/docs/authentication/programmatic-auth-configs.md)** for the toolkit you're importing into
2. **The existing credentials** for each user (API keys, bearer tokens, username/password, etc.)
3. **A userID** for each user. Any string that uniquely identifies them in your system.

## API keys

For services that use API key authentication (e.g., SendGrid, Tavily, PostHog):

> [tab] Python
>
> ```python theme={null}
> from composio import Composio
> from composio.types import auth_scheme
>
> composio = Composio(api_key="your-api-key")
>
> connection = composio.connected_accounts.initiate(
>     user_id="user_123",
>     auth_config_id="ac_your_auth_config",
>     # The helper fills status="ACTIVE"; its generated input type still requires it.
>     config=auth_scheme.api_key({  # type: ignore[arg-type]
>         "api_key": "sg-existing-sendgrid-key",
>     }),
> )
>
> # API key connections are immediately active
> print(f"Connected: {connection.id}")
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio, AuthScheme } from '@composio/core';
>
> const composio = new Composio({ apiKey: 'your-api-key' });
>
> const connection = await composio.connectedAccounts.initiate(
>   'user_123',
>   'ac_your_auth_config',
>   {
>     config: AuthScheme.APIKey({
>       api_key: 'sg-existing-sendgrid-key',
>     }),
>   }
> );
>
> // API key connections are immediately active
> console.log('Connected:', connection.id);
> ```

> [tab] API
>
> ```bash theme={null}
> # API key connections are immediately active
> curl -X POST https://backend.composio.dev/api/v3.1/connected_accounts \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "auth_config": {"id": "ac_your_auth_config"},
>     "connection": {
>       "user_id": "user_123",
>       "state": {"authScheme": "API_KEY", "val": {"status": "ACTIVE", "api_key": "sg-existing-sendgrid-key"}}
>     }
>   }' | jq -r '.id'
> ```

## Bearer tokens

If you manage your own OAuth flow and already have an access token for a service, you can import it into Composio as a bearer token. This lets you bring existing OAuth connections into Composio without re-authenticating your users. It works with **all toolkits that support OAuth2 or S2S auth** (Gmail, GitHub, Slack, Google Docs, and more). Any additional parameters the toolkit supports (e.g., `subdomain`, `base_url`) work the same way.

Since you're providing your own token, Composio won't handle OAuth refresh. You're responsible for refreshing the token on your end and pushing the updated value to Composio via the [PATCH method](#updating-credentials) whenever it changes.

After [creating an auth config](https://composio-preview.mintlify.site/docs/authentication/programmatic-auth-configs.md) with `authScheme: "BEARER_TOKEN"`, use the snippet below to create a connected account:

> [tab] Python
>
> ```python theme={null}
> from composio import Composio
> from composio.types import auth_scheme
>
> composio = Composio(api_key="your-api-key")
>
> connection = composio.connected_accounts.initiate(
>     user_id="user_123",
>     auth_config_id="ac_your_auth_config",
>     # The helper fills status="ACTIVE"; its generated input type still requires it.
>     config=auth_scheme.bearer_token({  # type: ignore[arg-type]
>         "token": "existing-bearer-token",
>     }),
> )
>
> # Bearer token connections are immediately active
> print(f"Connected: {connection.id}")
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio, AuthScheme } from '@composio/core';
>
> const composio = new Composio({ apiKey: 'your-api-key' });
>
> const connection = await composio.connectedAccounts.initiate(
>   'user_123',
>   'ac_your_auth_config',
>   {
>     config: AuthScheme.BearerToken({
>       token: 'existing-bearer-token',
>     }),
>   }
> );
>
> // Bearer token connections are immediately active
> console.log('Connected:', connection.id);
> ```

> [tab] API
>
> ```bash theme={null}
> # Bearer token connections are immediately active
> curl -X POST https://backend.composio.dev/api/v3.1/connected_accounts \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "auth_config": {"id": "ac_your_auth_config"},
>     "connection": {
>       "user_id": "user_123",
>       "state": {"authScheme": "BEARER_TOKEN", "val": {"status": "ACTIVE", "token": "existing-bearer-token"}}
>     }
>   }' | jq -r '.id'
> ```

## Basic auth

> [tab] Python
>
> ```python theme={null}
> from composio import Composio
> from composio.types import auth_scheme
>
> composio = Composio(api_key="your-api-key")
>
> connection = composio.connected_accounts.initiate(
>     user_id="user_123",
>     auth_config_id="ac_your_auth_config",
>     # The helper fills status="ACTIVE"; its generated input type still requires it.
>     config=auth_scheme.basic({  # type: ignore[arg-type]
>         "username": "user@example.com",
>         "password": "existing-password",
>     }),
> )
>
> # Basic auth connections are immediately active
> print(f"Connected: {connection.id}")
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio, AuthScheme } from '@composio/core';
>
> const composio = new Composio({ apiKey: 'your-api-key' });
>
> const connection = await composio.connectedAccounts.initiate(
>   'user_123',
>   'ac_your_auth_config',
>   {
>     config: AuthScheme.Basic({
>       username: 'user@example.com',
>       password: 'existing-password',
>     }),
>   }
> );
>
> // Basic auth connections are immediately active
> console.log('Connected:', connection.id);
> ```

> [tab] API
>
> ```bash theme={null}
> # Basic auth connections are immediately active
> curl -X POST https://backend.composio.dev/api/v3.1/connected_accounts \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "auth_config": {"id": "ac_your_auth_config"},
>     "connection": {
>       "user_id": "user_123",
>       "state": {"authScheme": "BASIC", "val": {"status": "ACTIVE", "username": "user@example.com", "password": "existing-password"}}
>     }
>   }' | jq -r '.id'
> ```

## Updating credentials

When credentials expire or rotate, update them in place without recreating the connection. Fields you omit are preserved. Fields set to `null` are removed.

> [tab] Bearer token
>
> > [tab] Python
> >
> > ```python theme={null}
> > from composio.client.types import connected_account_patch_params
> >
> > connection: connected_account_patch_params.Connection = {
> >     "state": {
> >         "auth_scheme": "BEARER_TOKEN",
> >         "val": {"token": "new-access-token"},
> >     },
> > }
> > composio.connected_accounts.update("ca_your_connection_id", connection=connection)
> > ```
>
> > [tab] TypeScript
> >
> > ```typescript theme={null}
> > import { Composio } from '@composio/core';
> > const composio = new Composio({ apiKey: 'your-api-key' });
> > await composio.connectedAccounts.update('ca_your_connection_id', {
> >   connection: {
> >     state: {
> >       authScheme: 'BEARER_TOKEN',
> >       val: { token: 'new-access-token' },
> >     },
> >   },
> > });
> > ```
>
> > [tab] API
> >
> > ```bash theme={null}
> > curl -X PATCH https://backend.composio.dev/api/v3.1/connected_accounts/ca_your_connection_id \
> >   -H "x-api-key: $COMPOSIO_API_KEY" \
> >   -H "Content-Type: application/json" \
> >   -d '{"connection":{"state":{"authScheme":"BEARER_TOKEN","val":{"token":"new-access-token"}}}}'
> > ```

> [tab] API key
>
> > [tab] Python
> >
> > ```python theme={null}
> > from composio.client.types import connected_account_patch_params
> >
> > connection: connected_account_patch_params.Connection = {
> >     "state": {
> >         "auth_scheme": "API_KEY",
> >         "val": {"generic_api_key": "new-api-key"},
> >     },
> > }
> > composio.connected_accounts.update("ca_your_connection_id", connection=connection)
> > ```
>
> > [tab] TypeScript
> >
> > ```typescript theme={null}
> > import { Composio } from '@composio/core';
> > const composio = new Composio({ apiKey: 'your-api-key' });
> > await composio.connectedAccounts.update('ca_your_connection_id', {
> >   connection: {
> >     state: {
> >       authScheme: 'API_KEY',
> >       val: { generic_api_key: 'new-api-key' },
> >     },
> >   },
> > });
> > ```
>
> > [tab] API
> >
> > ```bash theme={null}
> > curl -X PATCH https://backend.composio.dev/api/v3.1/connected_accounts/ca_your_connection_id \
> >   -H "x-api-key: $COMPOSIO_API_KEY" \
> >   -H "Content-Type: application/json" \
> >   -d '{"connection":{"state":{"authScheme":"API_KEY","val":{"generic_api_key":"new-api-key"}}}}'
> > ```

> [tab] Basic auth
>
> > [tab] Python
> >
> > ```python theme={null}
> > from composio.client.types import connected_account_patch_params
> >
> > connection: connected_account_patch_params.Connection = {
> >     "state": {
> >         "auth_scheme": "BASIC",
> >         "val": {"username": "user@example.com", "password": "new-password"},
> >     },
> > }
> > composio.connected_accounts.update("ca_your_connection_id", connection=connection)
> > ```
>
> > [tab] TypeScript
> >
> > ```typescript theme={null}
> > import { Composio } from '@composio/core';
> > const composio = new Composio({ apiKey: 'your-api-key' });
> > await composio.connectedAccounts.update('ca_your_connection_id', {
> >   connection: {
> >     state: {
> >       authScheme: 'BASIC',
> >       val: { username: 'user@example.com', password: 'new-password' },
> >     },
> >   },
> > });
> > ```
>
> > [tab] API
> >
> > ```bash theme={null}
> > curl -X PATCH https://backend.composio.dev/api/v3.1/connected_accounts/ca_your_connection_id \
> >   -H "x-api-key: $COMPOSIO_API_KEY" \
> >   -H "Content-Type: application/json" \
> >   -d '{"connection":{"state":{"authScheme":"BASIC","val":{"username":"user@example.com","password":"new-password"}}}}'
> > ```

## Using in your session

Pass the auth config or connection ID when creating a session:

> [tab] Python
>
> ```python theme={null}
> session = composio.create(
>     user_id="user_123",
>     auth_configs={"gmail": "ac_your_auth_config"},
>     toolkits=["gmail"],
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your-api-key' });
> const session = await composio.create('user_123', {
>   authConfigs: { gmail: 'ac_your_auth_config' },
>   toolkits: ['gmail'],
> });
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "user_id": "user_123",
>     "auth_configs": {"gmail": "ac_your_auth_config"},
>     "toolkits": {"enable": ["gmail"]}
>   }'
> ```

## Next

> [card] [Managing multiple accounts](https://composio-preview.mintlify.site/docs/authentication/managing-multiple-connected-accounts.md)
>
> Pin and select connected accounts for a user
