@devries-cameron20 / composio-1 / commits / b17b4de37
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

docs: add direct customAuthParams usage to custom auth params page

Lead with the simple inline approach (pass credentials directly in tools.execute) since that's what most BYOT users want. The beforeExecute modifier pattern is kept as an advanced option for conditional logic. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Sushmitha Mallesh committed Mar 18, 2026 at 12:24 UTC b17b4de37f99b9a0911e1746d1c0ebbdee79f32b
1 file changed +73 -51
docs/content/docs/auth-configuration/custom-auth-params.mdx
+73 -51
@@ -1,7 +1,7 @@
1 ---
2 title: Custom Auth Parameters
3 description: Inject custom credentials in headers or parameters
4 -keywords: [inject headers, custom credentials]
4 +keywords: [inject headers, custom credentials, BYOT, bring your own token, OAuth token, access token]
5 llmGuardrails: "direct-execution"
6 ---
7
@@ -9,11 +9,11 @@ llmGuardrails: "direct-execution"
9 If you're building an agent, we recommend using [sessions](/docs/configuring-sessions) instead. Sessions handle authentication automatically via [in-chat authentication](/docs/authenticating-users/in-chat-authentication) or [manual authentication](/docs/authenticating-users/manually-authenticating).
10 </Callout>
11
12 -In cases where Composio is not being used for managing the auth but only for the tools, it is possible to use the `beforeExecute` hook to inject custom auth headers or parameters for a toolkit.
12 +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.
13
14 -## Setup and Initialization
14 +## Passing credentials directly
15
16 -First, initialize the Composio SDK with your API key:
16 +Pass `customAuthParams` in the `tools.execute()` call to inject your own token as a header or query parameter.
17
18 <Tabs groupId="language" items={['Python', 'TypeScript']} persist>
19 <Tab value="Python">
@@ -21,6 +21,22 @@ First, initialize the Composio SDK with your API key:
21 from composio import Composio
22
23 composio = Composio()
24 +
25 +result = composio.tools.execute(
26 + slug="GOOGLECALENDAR_LIST_EVENTS",
27 + user_id="user_123",
28 + arguments={},
29 + custom_auth_params={
30 + "parameters": [
31 + {
32 + "name": "Authorization",
33 + "value": "Bearer YOUR_ACCESS_TOKEN",
34 + "in": "header",
35 + }
36 + ],
37 + },
38 +)
39 +print(result)
40 ```
41 </Tab>
42 <Tab value="TypeScript">
@@ -30,13 +46,48 @@ import { Composio } from "@composio/core";
46 const composio = new Composio({
47 apiKey: process.env.COMPOSIO_API_KEY,
48 });
49 +
50 +const result = await composio.tools.execute(
51 + "GOOGLECALENDAR_LIST_EVENTS",
52 + {
53 + userId: "user_123",
54 + arguments: {},
55 + customAuthParams: {
56 + parameters: [
57 + {
58 + in: "header",
59 + name: "Authorization",
60 + value: `Bearer ${process.env.GOOGLE_ACCESS_TOKEN}`,
61 + },
62 + ],
63 + },
64 + }
65 +);
66 +
67 +console.log(JSON.stringify(result, null, 2));
68 ```
69 </Tab>
70 </Tabs>
71
37 -## Creating the Auth Modifier Function
72 +<Callout type="warn">
73 +This bypasses Composio's automatic token refresh. You are responsible for refreshing expired tokens yourself.
74 +</Callout>
75 +
76 +### Parameter options
77 +
78 +Each entry in the `parameters` array accepts:
79 +
80 +| Field | Description |
81 +|-------|-------------|
82 +| `name` | The parameter name (e.g., `Authorization`, `X-API-Key`) |
83 +| `value` | The credential value |
84 +| `in` | Where to inject — `"header"` or `"query"` |
85 +
86 +You can also set `base_url` (Python) / `baseURL` (TypeScript) to override the default API base URL for the toolkit.
87
39 -Define a function that modifies authentication parameters for specific toolkits. This function checks the toolkit name and adds custom authentication headers when needed.
88 +## Using a beforeExecute modifier
89 +
90 +For more control — such as conditionally injecting credentials based on toolkit or tool — use a `beforeExecute` modifier.
91
92 <Card title="This is a Before Execute Modifier!" href="/docs/tools-direct/modify-tool-behavior/before-execution-modifiers">
93 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.
@@ -45,9 +96,11 @@ Before Execute Modifiers are a way to modify the parameters of a tool before it
96 <Tabs groupId="language" items={['Python', 'TypeScript']} persist>
97 <Tab value="Python">
98 ```python
48 -from composio import before_execute
99 +from composio import Composio, before_execute
100 from composio.types import ToolExecuteParams
101
102 +composio = Composio()
103 +
104
105 @before_execute(toolkits=["NOTION"])
106 def add_custom_auth(
@@ -66,6 +119,17 @@ def add_custom_auth(
119 }
120 )
121 return params
122 +
123 +
124 +result = composio.tools.execute(
125 + slug="NOTION_GET_DATABASE_ITEMS",
126 + user_id="user_123",
127 + arguments={},
128 + modifiers=[
129 + add_custom_auth,
130 + ],
131 +)
132 +print(result)
133 ```
134 </Tab>
135 <Tab value="TypeScript">
@@ -74,17 +138,11 @@ import { Composio } from '@composio/core';
138 const composio = new Composio({ apiKey: 'your_api_key' });
139 // ---cut---
140 const authModifier = ({ toolSlug, toolkitSlug, params }: { toolSlug: string; toolkitSlug: string; params: any }) => {
77 - // Add authentication parameters for specific toolkits
141 if (toolkitSlug === "NOTION") {
142 if (!params.customAuthParams) {
80 - params.customAuthParams = {};
81 - }
82 -
83 - if (!params.customAuthParams.parameters) {
84 - params.customAuthParams.parameters = [];
143 + params.customAuthParams = { parameters: [] };
144 }
145
87 - // Add an API key to the headers
146 params.customAuthParams.parameters.push({
147 in: "header",
148 name: "X-API-Key",
@@ -93,47 +151,11 @@ const authModifier = ({ toolSlug, toolkitSlug, params }: { toolSlug: string; too
151 }
152 return params;
153 };
96 -```
97 - </Tab>
98 -</Tabs>
99 -
100 -## Executing Tools with Custom Auth
101 -
102 -Execute the tool using the custom authentication modifier. The `beforeExecute` hook allows you to modify parameters before the tool runs.
154
104 -Following is an example of how to execute a tool with a custom authentication modifier for Completion Providers.
105 -
106 -For Agentic Providers, read about [Modifying tool inputs](/docs/tools-direct/modify-tool-behavior/before-execution-modifiers).
107 -
108 -<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
109 - <Tab value="Python">
110 -```python
111 -result = composio.tools.execute(
112 - slug="NOTION_GET_DATABASE_ITEMS",
113 - user_id="default",
114 - arguments={},
115 - modifiers=[
116 - add_custom_auth,
117 - ],
118 -)
119 -print(result)
120 -```
121 - </Tab>
122 - <Tab value="TypeScript">
123 -```typescript
124 -import { Composio } from '@composio/core';
125 -const composio = new Composio({ apiKey: 'your_api_key' });
126 -const authModifier = ({ toolSlug, toolkitSlug, params }: { toolSlug: string; toolkitSlug: string; params: any }) => {
127 - if (toolkitSlug === 'NOTION' && !params.customAuthParams) {
128 - params.customAuthParams = { parameters: [{ in: 'header', name: 'X-API-Key', value: 'key' }] };
129 - }
130 - return params;
131 -};
132 -// ---cut---
155 const result = await composio.tools.execute(
156 "NOTION_GET_DATABASE_ITEMS",
157 {
136 - userId: "sid",
158 + userId: "user_123",
159 arguments: {
160 database_id: "1234567890",
161 },