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

next
md 215 lines 6.19 KB
Rendered Raw
1 ---
2 type: "guide"
3 title: "Create Read-Only and Restricted Composio Sessions"
4 description: "Public guidance for limiting session tool access with tags, exact tool allowlists, OAuth scopes, and sandbox controls."
5 category: "authentication"
6 visibility: "public"
7 timestamp: "2026-08-24T00:00:00Z"
8 tags:
9 - "read-only"
10 - "tool-policy"
11 - "least-privilege"
12 - "oauth-scopes"
13 - "sessions"
14 ---
15 # Create Read-Only and Restricted Composio Sessions
16
17 ## Filter a broad read-only session with behavior tags
18
19 Use session-level behavior tags when the agent may discover tools across
20 multiple toolkits but should only receive tools marked as read-only. The same
21 filters are enforced when the session executes tools.
22
23 ### Python
24
25 ```python
26 session = composio.sessions.create(
27 user_id="user_123",
28 tags={
29 "enable": ["readOnlyHint"],
30 "disable": ["destructiveHint"],
31 },
32 )
33 ```
34
35 ### TypeScript
36
37 ```typescript
38 import { Composio } from "@composio/core";
39
40 const composio = new Composio();
41 const session = await composio.create("user_123", {
42 tags: {
43 enable: ["readOnlyHint"],
44 disable: ["destructiveHint"],
45 },
46 });
47 ```
48
49 ### API
50
51 ```bash
52 curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
53 -H "x-api-key: $COMPOSIO_API_KEY" \
54 -H "Content-Type: application/json" \
55 -d '{"user_id":"user_123","tags":{"enable":["readOnlyHint"],"disable":["destructiveHint"]}}'
56 ```
57
58 <!-- end-languages -->
59
60 Behavior tags describe tool behavior. Inspect the tools the session exposes
61 before rollout, especially when a workflow handles sensitive data.
62
63 - [Filter tools by tags](https://docs.composio.dev/docs/configuring-sessions#filtering-tools-by-tags)
64
65 ## Use exact tool allowlists for the narrowest policy
66
67 For a workflow with a known set of operations, allow only the exact tool slugs
68 it requires. An allowlist avoids admitting a newly added tool merely because it
69 shares a toolkit or behavior tag.
70
71 ### Python
72
73 ```python
74 session = composio.sessions.create(
75 user_id="user_123",
76 tools={
77 "gmail": {"enable": ["GMAIL_FETCH_EMAILS"]},
78 "github": {"enable": ["GITHUB_GET_AN_ISSUE"]},
79 },
80 )
81 ```
82
83 ### TypeScript
84
85 ```typescript
86 import { Composio } from "@composio/core";
87
88 const composio = new Composio();
89 const session = await composio.create("user_123", {
90 tools: {
91 gmail: { enable: ["GMAIL_FETCH_EMAILS"] },
92 github: { enable: ["GITHUB_GET_AN_ISSUE"] },
93 },
94 });
95 ```
96
97 ### API
98
99 ```bash
100 curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
101 -H "x-api-key: $COMPOSIO_API_KEY" \
102 -H "Content-Type: application/json" \
103 -d '{"user_id":"user_123","tools":{"gmail":{"enable":["GMAIL_FETCH_EMAILS"]},"github":{"enable":["GITHUB_GET_AN_ISSUE"]}}}'
104 ```
105
106 <!-- end-languages -->
107
108 - [Enable and disable specific tools](https://docs.composio.dev/docs/configuring-sessions#enabling-or-disabling-specific-tools)
109
110 An Auth Config's tool access allowlist applies when tools are listed through
111 that Auth Config's tools API and on the older MCP path. It does not restrict
112 tool discovery or execution in a Tool Router session. To restrict a session,
113 configure its session-level tools or toolkit settings when creating the
114 session; those restrictions apply to both discovery and execution.
115
116 ## Combine provider scopes with session tool restrictions
117
118 OAuth scopes control what the provider grants to a connected account. Session
119 filters control which Composio tools the agent can discover and execute. Use
120 both layers for least privilege: request only the provider scopes the use case
121 needs, then restrict the session to the intended tools.
122
123 Changing an auth config's scopes affects new connections only. Existing users
124 keep their prior grants until they reconnect. Pass the intended auth config ID
125 to the session, keyed by toolkit, or the session will not request those scopes.
126
127 - [Control OAuth scopes](https://docs.composio.dev/docs/authentication/controlling-scopes)
128 - [Select an auth config in a session](https://docs.composio.dev/docs/authentication/custom-app-vs-managed-app#create-a-custom-auth-config)
129
130 ## Apply toolkit-specific exceptions without widening every toolkit
131
132 Set a global tag policy and override it only for a named toolkit. This is safer
133 than relaxing the global policy for the entire session.
134
135 ### Python
136
137 ```python
138 session = composio.sessions.create(
139 user_id="user_123",
140 tags=["readOnlyHint"],
141 tools={
142 "github": {"tags": {"disable": ["destructiveHint"]}},
143 "gmail": {"tags": ["readOnlyHint"]},
144 },
145 )
146 ```
147
148 ### TypeScript
149
150 ```typescript
151 import { Composio } from "@composio/core";
152
153 const composio = new Composio();
154 const session = await composio.create("user_123", {
155 tags: ["readOnlyHint"],
156 tools: {
157 github: { tags: { disable: ["destructiveHint"] } },
158 gmail: { tags: ["readOnlyHint"] },
159 },
160 });
161 ```
162
163 ### API
164
165 ```bash
166 curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
167 -H "x-api-key: $COMPOSIO_API_KEY" \
168 -H "Content-Type: application/json" \
169 -d '{"user_id":"user_123","tags":["readOnlyHint"],"tools":{"github":{"tags":{"disable":["destructiveHint"]}},"gmail":{"tags":["readOnlyHint"]}}}'
170 ```
171
172 <!-- end-languages -->
173
174 - [Toolkit-specific tag filters](https://docs.composio.dev/docs/configuring-sessions#filtering-tools-by-tags)
175
176 ## Disable the session sandbox when the workflow does not need code execution
177
178 Session tool filters govern app tools. Sessions also include remote sandbox
179 tools by default. Disable the sandbox for a tightly constrained workflow that
180 does not need Python, shell, file processing, or remote workbench execution.
181
182 ### Python
183
184 ```python
185 session = composio.sessions.create(
186 user_id="user_123",
187 tags=["readOnlyHint"],
188 sandbox={"enable": False},
189 )
190 ```
191
192 ### TypeScript
193
194 ```typescript
195 import { Composio } from "@composio/core";
196
197 const composio = new Composio();
198 const session = await composio.create("user_123", {
199 tags: ["readOnlyHint"],
200 sandbox: { enable: false },
201 });
202 ```
203
204 ### API
205
206 ```bash
207 curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
208 -H "x-api-key: $COMPOSIO_API_KEY" \
209 -H "Content-Type: application/json" \
210 -d '{"user_id":"user_123","tags":["readOnlyHint"],"workbench":{"enable":false}}'
211 ```
212
213 <!-- end-languages -->
214
215 - [Disable the session sandbox](https://docs.composio.dev/docs/configuring-sessions#disabling-the-sandbox)