> ## 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.

# Managed authentication for your own tools

> Connect each user's accounts and call provider APIs from your own tools without handling OAuth tokens

Use Composio to connect your users' accounts and authenticate API requests from your own tools. Your tool definitions and business logic stay in your application. Composio stores and refreshes credentials, sends requests to the provider, and returns the response. You don't need predefined Composio tools, MCP, or an LLM.

## Connect an account and call its API

This example connects GitHub and reads the connected account's profile through `GET /user`. Install the SDK with `pip install composio` or `npm install @composio/core`. Set `COMPOSIO_API_KEY` in your backend environment. The API example also needs Bash and `jq`.

For a [scoped project API key](https://composio-preview.mintlify.site/reference/authenticating-to-composio/project-api-key-permissions.md), enable **Session management → Write only**, **Connected accounts → Read only**, and **Proxy execute (Legacy) → Write only**. Default full-access project keys already include these permissions. Keep the key server-side.

The example uses `org_42:user_7` as an illustrative connection owner. In your application, derive this value from the authenticated request after checking workspace membership. Never accept a model-supplied or browser-supplied owner ID as authorization. See [B2B connection ownership](https://composio-preview.mintlify.site/docs/b2b-agents.md#choose-the-connection-owner) for member-owned and workspace-owned connections.

This example uses a session to create the Connect Link. Subsequent API calls pass the owner and connected-account ID directly.

> [tab] Python
>
> ```python theme={null}
> from composio import Composio
>
> composio = Composio()
>
> # Resolve this owner from your authenticated application session.
> owner_id = "org_42:user_7"
> session = composio.create(user_id=owner_id, toolkits=["github"])
> connection = session.authorize("github")
> print(f"Open this Connect Link: {connection.redirect_url}")
> account = connection.wait_for_connection(60)
>
> def read_github_profile(connected_account_id: str):
>     return composio.tools.proxy(
>         user_id=owner_id,
>         connected_account_id=connected_account_id,
>         endpoint="/user",
>         method="GET",
>     )
>
> # Use the account returned by this owner's connection attempt.
> response = read_github_profile(account.id)
> print(response.status)
> print(response.data)
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
>
> const composio = new Composio();
>
> // Resolve this owner from your authenticated application session.
> const ownerId = 'org_42:user_7';
> const session = await composio.create(ownerId, { toolkits: ['github'] });
> const connection = await session.authorize('github');
> console.log(`Open this Connect Link: ${connection.redirectUrl}`);
> const account = await connection.waitForConnection(60000);
>
> function readGitHubProfile(connectedAccountId: string) {
>   return composio.tools.proxyExecute({
>     userId: ownerId,
>     connectedAccountId,
>     endpoint: '/user',
>     method: 'GET',
>   });
> }
>
> // Use the account returned by this owner's connection attempt.
> const response = await readGitHubProfile(account.id);
> console.log(response.status);
> console.log(response.data);
> ```

> [tab] API
>
> ```bash theme={null}
> set -euo pipefail
>
> # Resolve this owner from your authenticated application session.
> OWNER_ID="org_42:user_7"
> SESSION_ID=$(curl --fail-with-body -s -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\":\"$OWNER_ID\",\"toolkits\":{\"enable\":[\"github\"]}}" | jq -r '.session_id')
>
> CONNECTION=$(curl --fail-with-body -s -X POST https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/link \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"toolkit":"github"}')
> echo "$CONNECTION" | jq -r '.redirect_url'
> CONNECTED_ACCOUNT_ID=$(echo "$CONNECTION" | jq -r '.connected_account_id')
>
> # Open the printed link. Wait at most 60 seconds for authorization.
> DEADLINE=$((SECONDS + 60))
> while true; do
>   ACCOUNT=$(curl --fail-with-body -s https://backend.composio.dev/api/v3.1/connected_accounts/$CONNECTED_ACCOUNT_ID \
>     -H "x-api-key: $COMPOSIO_API_KEY")
>   STATUS=$(echo "$ACCOUNT" | jq -r '.status')
>   case "$STATUS" in
>     ACTIVE) break ;;
>     FAILED|EXPIRED|REVOKED) echo "Connection ended: $STATUS" >&2; exit 1 ;;
>   esac
>   if [ "$SECONDS" -ge "$DEADLINE" ]; then
>     echo "Timed out waiting for authorization" >&2
>     exit 1
>   fi
>   sleep 1
> done
>
> # Use the account returned by this owner's connection attempt.
> curl --fail-with-body -s -X POST https://backend.composio.dev/api/v3.1/tools/execute/proxy \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d "{\"user_id\":\"$OWNER_ID\",\"connected_account_id\":\"$CONNECTED_ACCOUNT_ID\",\"endpoint\":\"/user\",\"method\":\"GET\"}" \
>   | jq '{status, data}'
> ```

Open the printed Connect Link and authorize GitHub within 60 seconds. The connection must become `ACTIVE` before the proxy request runs. During this wait, `INACTIVE` can still become `ACTIVE`, so keep polling until the deadline. Stop immediately on `FAILED`, `EXPIRED`, or `REVOKED`. The proxy returns the provider's response, not its OAuth token. No tool schemas are fetched and no model selects an action.

The [proxy response](https://composio-preview.mintlify.site/reference/api-reference/tools/postToolsExecuteProxy.md) contains the provider's response body in `data`, HTTP status in `status`, and response headers in `headers`.

The direct proxy call is independent of the session: pass both the owner (`user_id` in Python and REST, `userId` in TypeScript) and the exact returned connected-account ID. Projects with 2FA enabled check the owner against the connected account and may require it. Your own tool can call `read_github_profile()` or `readGitHubProfile()` from any framework, or you can make the equivalent REST request from your backend.

## Reuse connections in your application

For onboarding or a settings page, send the Connect Link to the browser and persist the connection attempt server-side rather than holding an HTTP request open while the person signs in. When creating the Connect Link, pass your application's callback URL through `callback_url` in Python and REST, or `callbackUrl` in TypeScript. See [Redirecting users after authentication](https://composio-preview.mintlify.site/docs/authentication/manually-authenticating.md#redirecting-users-after-authentication) for setup.

On callback, verify that the connected-account ID belongs to that attempt and the signed-in owner, then retrieve its current status. Callback query parameters aren't proof of ownership. See [Identify the connected account](https://composio-preview.mintlify.site/docs/authentication/manually-authenticating.md#identify-the-connected-account).

Store the verified connected-account ID with your tenant/member mapping. On subsequent requests, authorize the caller and resolve that stored mapping before calling the proxy. Don't expose an endpoint that accepts arbitrary connected-account IDs from a browser or model.

If authorization fails or times out, don't call the provider. If a connection expires or is revoked, stop using it and ask its owner to reconnect. Subscribe to the [connection expiration event](https://composio-preview.mintlify.site/docs/authentication#connection-lifecycle) to surface reconnect prompts before a request fails. Don't automatically retry side-effecting provider requests; see [retry failed executions deliberately](https://composio-preview.mintlify.site/docs/production-readiness.md#retry-failed-executions-deliberately).

## Choose your OAuth app separately

Keep Composio-managed OAuth apps in production when their consent branding, scopes, and shared provider quotas fit your product. Use a [custom auth config](https://composio-preview.mintlify.site/docs/authentication/custom-app-vs-managed-app.md) when you need your own OAuth app, different scopes, dedicated quotas, or a custom provider instance. Composio still manages the resulting connected-account credentials in either case.

## Understand the boundaries

> [!WARNING]
>
> **Managed authentication is not token export**
>
> This is managed authentication for your own tools, not a token-export service. Connected-account reads redact credentials and aren't a supported way to retrieve access or refresh tokens. A custom OAuth app doesn't move token custody out of Composio Cloud. If your local vendor SDK requires a raw token, this proxy pattern doesn't supply one. Review [token custody and deployment options](https://composio-preview.mintlify.site/docs/security/token-custody.md) instead of attempting to extract credentials from account state.

* **Provider scope:** Use relative paths for the connected provider. Proxy Execute is not an arbitrary authenticated HTTP relay; absolute URLs must keep the connected provider's scheme and registrable domain.
* **Authorization:** Proxy permission can allow operations beyond predefined tool schemas. Validate endpoints and inputs in your own tools, enforce your application's tenant and role checks, and request only the provider scopes you need.
* **Deployment:** Private VPC and self-hosted deployments are Enterprise arrangements. Customer-managed keys require a separate deployment design with Composio. Confirm operator access, decryption, logs, and backups against your requirements.

## Next

> [card] [Proxy Execute](https://composio-preview.mintlify.site/docs/extending-sessions/proxy-execute.md)
>
> Call provider endpoints from a session and understand proxy restrictions.

> [card] [Custom tools and toolkits](https://composio-preview.mintlify.site/docs/extending-sessions/custom-tools-and-toolkits.md)
>
> Optionally expose your custom business logic through experimental session extension tools.

> [card] [Token custody architecture](https://composio-preview.mintlify.site/docs/security/token-custody.md)
>
> Review credential redaction, OAuth app ownership, and deployment boundaries.
