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

# Custom Auth Parameters

> Inject custom credentials in headers or parameters

> [!NOTE]
>
> If you're building an agent, we recommend using [sessions](https://composio-preview.mintlify.site/docs/configuring-sessions.md) instead. Sessions handle authentication automatically via [in-chat authentication](https://composio-preview.mintlify.site/docs/authentication#in-chat-authentication) or [manual authentication](https://composio-preview.mintlify.site/docs/authentication/manually-authenticating.md).

If you already manage OAuth tokens or API keys yourself and want Composio to execute tools using your credentials, you can pass them directly at execution time — no connected account or redirect flow required.

## Passing credentials directly

Pass `customAuthParams` in the `tools.execute()` call to inject your own token as a header or query parameter.

> [tab] Python
>
> ```python theme={null}
> import os
>
> from composio import Composio
> from composio.client.types import tool_execute_params
>
> composio = Composio(toolkit_versions={"googlecalendar": "latest"})
>
> auth_params: tool_execute_params.CustomAuthParams = {
>     "parameters": [
>         {
>             "name": "Authorization",
>             "value": f"Bearer {os.environ['GOOGLE_ACCESS_TOKEN']}",
>             "in_": "header",  # Python field name; serialized as "in" on the wire
>         }
>     ],
> }
>
> result = composio.tools.execute(
>     slug="GOOGLECALENDAR_LIST_EVENTS",
>     user_id="user_123",
>     arguments={},
>     dangerously_skip_version_check=True,  # required when running "latest"
>     custom_auth_params=auth_params,
> )
> print(result)
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from "@composio/core";
>
> const composio = new Composio({
>   apiKey: process.env.COMPOSIO_API_KEY,
>   toolkitVersions: { googlecalendar: "latest" },
> });
>
> const result = await composio.tools.execute(
>   "GOOGLECALENDAR_LIST_EVENTS",
>   {
>     userId: "user_123",
>     arguments: {},
>     dangerouslySkipVersionCheck: true, // required when running "latest"
>     customAuthParams: {
>       parameters: [
>         {
>           in: "header",
>           name: "Authorization",
>           value: `Bearer ${process.env.GOOGLE_ACCESS_TOKEN}`,
>         },
>       ],
>     },
>   }
> );
>
> console.log(JSON.stringify(result, null, 2));
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X POST https://backend.composio.dev/api/v3.1/tools/execute/GOOGLECALENDAR_LIST_EVENTS \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "user_id": "user_123",
>     "version": "latest",
>     "arguments": {},
>     "custom_auth_params": {
>       "parameters": [
>         {"name": "Authorization", "value": "Bearer '"$GOOGLE_ACCESS_TOKEN"'", "in": "header"}
>       ]
>     }
>   }'
> ```

> [!WARNING]
>
> This bypasses Composio's automatic token refresh. You are responsible for refreshing expired tokens yourself.

### Parameter options

Each entry in the `parameters` array accepts:

| Field | Description |
| - | - |
| `name` | The parameter name (e.g., `Authorization`, `X-API-Key`) |
| `value` | The credential value |
| `in` | Where to inject — `"header"` or `"query"` |

You can also set `base_url` (Python) / `baseURL` (TypeScript) to override the default API base URL for the toolkit.

## Using a beforeExecute modifier

For more control — such as conditionally injecting credentials based on toolkit or tool — use a `beforeExecute` modifier.

> [card] [This is a Before Execute Modifier!](https://composio-preview.mintlify.site/docs/tools-direct/modify-tool-behavior/before-execution-modifiers.md)
>
> Before Execute Modifiers are a way to modify the parameters of a tool before it is executed. In this case, they are useful for adding custom authentication headers or parameters to a tool.

> [tab] Python
>
> ```python theme={null}
> import os
>
> from composio import Composio, before_execute
> from composio.types import ToolExecuteParams
>
> composio = Composio(toolkit_versions={"notion": "latest"})
>
> @before_execute(toolkits=["notion"])
> def add_custom_auth(
>     tool: str,
>     toolkit: str,
>     params: ToolExecuteParams,
> ) -> ToolExecuteParams:
>     if params.get("custom_auth_params") is None:
>         params["custom_auth_params"] = {"parameters": []}
>
>     params["custom_auth_params"]["parameters"].append(
>         {
>             "name": "x-api-key",
>             "value": os.environ["NOTION_API_KEY"],
>             "in_": "header",
>         }
>     )
>     return params
>
> result = composio.tools.execute(
>     slug="NOTION_GET_DATABASE_ITEMS",
>     user_id="user_123",
>     arguments={"database_id": "1234567890"},
>     dangerously_skip_version_check=True,  # required when running "latest"
>     modifiers=[
>         add_custom_auth,
>     ],
> )
> print(result)
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio, type beforeExecuteModifier } from '@composio/core';
>
> const composio = new Composio({
>   apiKey: process.env.COMPOSIO_API_KEY,
>   toolkitVersions: { notion: "latest" },
> });
>
> const addCustomAuth: beforeExecuteModifier = ({ toolkitSlug, params }) => {
>   if (toolkitSlug === "notion") {
>     if (!params.customAuthParams) {
>       params.customAuthParams = { parameters: [] };
>     }
>
>     params.customAuthParams.parameters.push({
>       in: "header",
>       name: "x-api-key",
>       value: process.env.NOTION_API_KEY!,
>     });
>   }
>   return params;
> };
>
> const result = await composio.tools.execute(
>   "NOTION_GET_DATABASE_ITEMS",
>   {
>     userId: "user_123",
>     arguments: {
>       database_id: "1234567890",
>     },
>     dangerouslySkipVersionCheck: true, // required when running "latest"
>   },
>   {
>     beforeExecute: addCustomAuth,
>   }
> );
>
> console.log(JSON.stringify(result, null, 2));
> ```

## Next

> [card] [Before execution modifiers](https://composio-preview.mintlify.site/docs/tools-direct/modify-tool-behavior/before-execution-modifiers.md)
>
> Modify tool arguments before execution
