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

# Create Read-Only and Restricted Composio Sessions

> Public guidance for limiting session tool access with tags, exact tool allowlists, OAuth scopes, and sandbox controls.

## Filter a broad read-only session with behavior tags

Use session-level behavior tags when the agent may discover tools across multiple toolkits but should only receive tools marked as read-only. The same filters are enforced when the session executes tools.

> [tab] Python
>
> ```python theme={null}
> session = composio.sessions.create(
>     user_id="user_123",
>     tags={
>         "enable": ["readOnlyHint"],
>         "disable": ["destructiveHint"],
>     },
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from "@composio/core";
>
> const composio = new Composio();
> const session = await composio.create("user_123", {
>   tags: {
>     enable: ["readOnlyHint"],
>     disable: ["destructiveHint"],
>   },
> });
> ```

> [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","tags":{"enable":["readOnlyHint"],"disable":["destructiveHint"]}}'
> ```

Behavior tags describe tool behavior. Inspect the tools the session exposes before rollout, especially when a workflow handles sensitive data.

* [Filter tools by tags](https://composio-preview.mintlify.site/docs/configuring-sessions.md#filtering-tools-by-tags)

## Use exact tool allowlists for the narrowest policy

For a workflow with a known set of operations, allow only the exact tool slugs it requires. An allowlist avoids admitting a newly added tool merely because it shares a toolkit or behavior tag.

> [tab] Python
>
> ```python theme={null}
> session = composio.sessions.create(
>     user_id="user_123",
>     tools={
>         "gmail": {"enable": ["GMAIL_FETCH_EMAILS"]},
>         "github": {"enable": ["GITHUB_GET_AN_ISSUE"]},
>     },
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from "@composio/core";
>
> const composio = new Composio();
> const session = await composio.create("user_123", {
>   tools: {
>     gmail: { enable: ["GMAIL_FETCH_EMAILS"] },
>     github: { enable: ["GITHUB_GET_AN_ISSUE"] },
>   },
> });
> ```

> [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","tools":{"gmail":{"enable":["GMAIL_FETCH_EMAILS"]},"github":{"enable":["GITHUB_GET_AN_ISSUE"]}}}'
> ```

* [Enable and disable specific tools](https://composio-preview.mintlify.site/docs/configuring-sessions.md#enabling-or-disabling-specific-tools)

## Combine provider scopes with session tool restrictions

OAuth scopes control what the provider grants to a connected account. Session filters control which Composio tools the agent can discover and execute. Use both layers for least privilege: request only the provider scopes the use case needs, then restrict the session to the intended tools.

Changing an auth config's scopes affects new connections only. Existing users keep their prior grants until they reconnect. Pass the intended auth config ID to the session, keyed by toolkit, or the session will not request those scopes.

* [Control OAuth scopes](https://composio-preview.mintlify.site/docs/authentication/controlling-scopes.md)
* [Select an auth config in a session](https://composio-preview.mintlify.site/docs/authentication/custom-app-vs-managed-app.md#create-a-custom-auth-config)

## Apply toolkit-specific exceptions without widening every toolkit

Set a global tag policy and override it only for a named toolkit. This is safer than relaxing the global policy for the entire session.

> [tab] Python
>
> ```python theme={null}
> session = composio.sessions.create(
>     user_id="user_123",
>     tags=["readOnlyHint"],
>     tools={
>         "github": {"tags": {"disable": ["destructiveHint"]}},
>         "gmail": {"tags": ["readOnlyHint"]},
>     },
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from "@composio/core";
>
> const composio = new Composio();
> const session = await composio.create("user_123", {
>   tags: ["readOnlyHint"],
>   tools: {
>     github: { tags: { disable: ["destructiveHint"] } },
>     gmail: { tags: ["readOnlyHint"] },
>   },
> });
> ```

> [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","tags":["readOnlyHint"],"tools":{"github":{"tags":{"disable":["destructiveHint"]}},"gmail":{"tags":["readOnlyHint"]}}}'
> ```

* [Toolkit-specific tag filters](https://composio-preview.mintlify.site/docs/configuring-sessions.md#filtering-tools-by-tags)

## Disable the session sandbox when the workflow does not need code execution

Session tool filters govern app tools. Sessions also include remote sandbox tools by default. Disable the sandbox for a tightly constrained workflow that does not need Python, shell, file processing, or remote workbench execution.

> [tab] Python
>
> ```python theme={null}
> session = composio.sessions.create(
>     user_id="user_123",
>     tags=["readOnlyHint"],
>     sandbox={"enable": False},
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from "@composio/core";
>
> const composio = new Composio();
> const session = await composio.create("user_123", {
>   tags: ["readOnlyHint"],
>   sandbox: { enable: false },
> });
> ```

> [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","tags":["readOnlyHint"],"workbench":{"enable":false}}'
> ```

* [Disable the session sandbox](https://composio-preview.mintlify.site/docs/configuring-sessions.md#disabling-the-sandbox)

Last verified <time dateTime="2026-08-24" />
