@devries-cameron20 / composio Mirror · read-only / commits / 0114fb2d2
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.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 09:45 UTC

docs: move Session configs to their own page

Configuring Sessions is getting long. The saved Session config section moves unchanged to /docs/session-configs, and Configuring Sessions keeps a short pointer to it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Mukund committed Oct 15, 2026 at 17:44 UTC 0114fb2d2bb511727f650c2e1d2153c90fce56c6
4 files changed +88 -79
docs/content/docs/configuring-sessions.mdx
+2 -78
@@ -37,83 +37,7 @@ Enable both permissions if your application manages sessions and executes tools
37
38 ## Using a saved Session config
39
40 -A **Session config** is a saved, named access policy (`sc_…`) that you build in the Composio Dashboard under Sessions → Configs. Start a session from one instead of repeating `toolkits`, `tools`, and `tags` in your code:
41 -
42 -```typescript
43 -// @noErrors
44 -import { Composio } from '@composio/core';
45 -const composio = new Composio({ apiKey: 'your_api_key' });
46 -// ---cut---
47 -const { items } = await composio.sessionConfigs.list({ search: "support" });
48 -
49 -const session = await composio.sessions.create("user_123", {
50 - authConfigs: { github: "ac_123" },
51 - experimental: { sessionConfigId: items[0].id },
52 -});
53 -
54 -console.log(session.experimental.sourceSessionConfig); // { id: "sc_..." }
55 -```
56 -
57 -The backend resolves the config when it creates the session, so the session gets exactly the access the config grants. Later edits to the config in the Dashboard don't change sessions that already exist.
58 -
59 -<Callout type="info">
60 -The top-level `composio.sessionConfigs` read methods are available in TypeScript. Applying a config and reading its source metadata use `experimental`. Reads require Session configs enabled for your project; otherwise they return `403`. With a [scoped project API key](/reference/authenticating-to-composio/project-api-key-permissions#session-management), they need the **Session management** read permission.
61 -</Callout>
62 -
63 -### Finding a config
64 -
65 -`composio.sessionConfigs.list()` returns summaries (`id`, `name`, `archived`, `createdAt`, `updatedAt`) and a `nextCursor`. It returns active configs unless you pass `archived: true`, which returns only archived ones. Pass `search` to match names and `limit` and `cursor` to page; the backend returns 20 per page by default and at most 100.
66 -
67 -`composio.sessionConfigs.get(id)` adds the `description` and the stored policy under `config`:
68 -
69 -```typescript
70 -// @noErrors
71 -import { Composio } from '@composio/core';
72 -const composio = new Composio({ apiKey: 'your_api_key' });
73 -// ---cut---
74 -const sessionConfig = await composio.sessionConfigs.get("sc_123");
75 -
76 -console.log(sessionConfig.config);
77 -// { toolkits: { enable: ["github"] }, tags: { disable: ["destructiveHint"] } }
78 -```
79 -
80 -A saved policy uses `enable` and `disable`, the same shape you send on create. `session.config` is the server's snapshot of a live session and names the same lists `enabled` and `disabled`.
81 -
82 -### What you can combine with a config
83 -
84 -The config owns the session's toolkit, tool, and tag access. On `create()`, you can't pass `sessionConfigId` together with `toolkits`, `tools`, `tags`, `experimental.customTools`, or `experimental.customToolkits`. TypeScript reports the mix at compile time, and the SDK throws `ValidationError` before it sends a request. An empty list such as `toolkits: []` counts as set.
85 -
86 -Per-session settings stay yours: `authConfigs`, `connectedAccounts`, `manageConnections`, `sandbox`, `multiAccount`, `preload`, `sessionPreset`, `mcp`, and `experimental.assistivePrompt`.
87 -
88 -`SessionPreset.DIRECT_TOOLS` defaults to `preload: { tools: "all" }` when you omit `preload`. With a saved config, the backend resolves its policy before validating that preload. The policy must select toolkits with `enable`, enable specific tools, or enable tags within a named toolkit's tool rule. An unrestricted policy, a denylist-only policy, or top-level tags alone returns `400`. The resolved tool set must also contain at most 1,000 tools.
89 -
90 -Live verification accepted `DIRECT_TOOLS` with a saved config that provided a positive toolkit/tool scope. The no-positive-scope case was not exercised in that run; its `400` behavior is enforced by the API's preload validation. The SDK passes these API errors through unchanged.
91 -
92 -### Applying a config to an existing session
93 -
94 -Pass `sessionConfigId` in the `experimental` block of `session.update()` to replace the session's toolkit, tool, and tag access with the config's policy. Other settings are preserved.
95 -
96 -```typescript
97 -// @noErrors
98 -import { Composio } from '@composio/core';
99 -const composio = new Composio({ apiKey: 'your_api_key' });
100 -// ---cut---
101 -const session = await composio.sessions.use("session_id");
102 -
103 -await session.update({ experimental: { sessionConfigId: "sc_123" } });
104 -```
105 -
106 -The same rule applies here: `sessionConfigId` can't be combined with `toolkits`, `tools`, or `tags`, and `null` counts as set. A saved config and custom tools don't mix on update either: if the session was created with inline custom tools, the backend rejects a conflicting config with a `400`.
107 -
108 -A `409` while applying a config means the session or the config changed during the update. The SDK raises `ComposioSessionConfigConflictError`, and nothing was written: re-fetch the session with `sessions.use()` and retry.
109 -
110 -### Which config a session came from
111 -
112 -`session.experimental.sourceSessionConfig` holds `{ id }` of the last config applied to the session. The SDK sets it after `create()`, `sessions.use()`, and a successful `update()`. It stays set after later inline updates such as `update({ toolkits: [...] })`, and it's `undefined` when no config was applied. It reflects the last response this session object saw, so an update from another process leaves it stale until you call `sessions.use()` again.
113 -
114 -### When a config can't be used
115 -
116 -The SDK never retries without the config or falls back to an unrestricted session. A missing, archived, or cross-project config fails with the backend's `404`, and a project without Session configs fails with `403`. A failed `update()` leaves the session object unchanged.
40 +To start a session from a saved access policy you build in the Composio Dashboard, see [Session configs](/docs/session-configs).
41
42 ## Reading and updating session configuration
43
@@ -999,7 +923,7 @@ await session.update({
923
924 Both blocks are on by default. `search` controls the session's search helper, so disabling it leaves the agent with the tools you preloaded. `execute.enableMultiExecute` controls whether the agent can run several tool calls in one request. `manageConnections.enableConnectionRemoval` is update-only as well, and controls whether the session exposes the connection-removal tool.
925
1002 -The `experimental` block on update holds server-side session settings: `permissions`, `linkUrlOverwrite`, `fastMode`, `submitFeedback`, and `sessionConfigId`. `sessionConfigId` applies a [saved Session config](#applying-a-config-to-an-existing-session) and can't be combined with `toolkits`, `tools`, or `tags`. The `experimental` block on update is a different field from the `experimental` option on `create()`, which holds [custom tools and toolkits](/docs/extending-sessions/custom-tools-and-toolkits) that run in your process, so `experimental: null` on an update leaves those alone.
926 +The `experimental` block on update holds server-side session settings: `permissions`, `linkUrlOverwrite`, `fastMode`, `submitFeedback`, and `sessionConfigId`. `sessionConfigId` applies a [saved Session config](/docs/session-configs#applying-a-config-to-an-existing-session) and can't be combined with `toolkits`, `tools`, or `tags`. The `experimental` block on update is a different field from the `experimental` option on `create()`, which holds [custom tools and toolkits](/docs/extending-sessions/custom-tools-and-toolkits) that run in your process, so `experimental: null` on an update leaves those alone.
927
928 ### Multi-account mode after an update
929
docs/content/docs/meta.json
+1
@@ -12,6 +12,7 @@
12 "---Core concepts---",
13 "how-composio-works",
14 "configuring-sessions",
15 + "session-configs",
16 "instant-tools",
17 "toolkits",
18 "authentication",
docs/content/docs/session-configs.mdx new
+83
@@ -0,0 +1,83 @@
1 +---
2 +title: Session configs
3 +description: Start or update sessions from a saved, named access policy you build in the Composio Dashboard
4 +keywords: [session config, sessionConfigId, saved config, access policy, dashboard]
5 +---
6 +
7 +A **Session config** is a saved, named access policy (`sc_…`) that you build in the Composio Dashboard under Sessions → Configs. Start a session from one instead of repeating `toolkits`, `tools`, and `tags` in your code:
8 +
9 +```typescript
10 +// @noErrors
11 +import { Composio } from '@composio/core';
12 +const composio = new Composio({ apiKey: 'your_api_key' });
13 +// ---cut---
14 +const { items } = await composio.sessionConfigs.list({ search: "support" });
15 +
16 +const session = await composio.sessions.create("user_123", {
17 + authConfigs: { github: "ac_123" },
18 + experimental: { sessionConfigId: items[0].id },
19 +});
20 +
21 +console.log(session.experimental.sourceSessionConfig); // { id: "sc_..." }
22 +```
23 +
24 +The backend resolves the config when it creates the session, so the session gets exactly the access the config grants. Later edits to the config in the Dashboard don't change sessions that already exist.
25 +
26 +<Callout type="info">
27 +The top-level `composio.sessionConfigs` read methods are available in TypeScript. Applying a config and reading its source metadata use `experimental`. Reads require Session configs enabled for your project; otherwise they return `403`. With a [scoped project API key](/reference/authenticating-to-composio/project-api-key-permissions#session-management), they need the **Session management** read permission.
28 +</Callout>
29 +
30 +## Finding a config
31 +
32 +`composio.sessionConfigs.list()` returns summaries (`id`, `name`, `archived`, `createdAt`, `updatedAt`) and a `nextCursor`. It returns active configs unless you pass `archived: true`, which returns only archived ones. Pass `search` to match names and `limit` and `cursor` to page; the backend returns 20 per page by default and at most 100.
33 +
34 +`composio.sessionConfigs.get(id)` adds the `description` and the stored policy under `config`:
35 +
36 +```typescript
37 +// @noErrors
38 +import { Composio } from '@composio/core';
39 +const composio = new Composio({ apiKey: 'your_api_key' });
40 +// ---cut---
41 +const sessionConfig = await composio.sessionConfigs.get("sc_123");
42 +
43 +console.log(sessionConfig.config);
44 +// { toolkits: { enable: ["github"] }, tags: { disable: ["destructiveHint"] } }
45 +```
46 +
47 +A saved policy uses `enable` and `disable`, the same shape you send on create. `session.config` is the server's snapshot of a live session and names the same lists `enabled` and `disabled`.
48 +
49 +## What you can combine with a config
50 +
51 +The config owns the session's toolkit, tool, and tag access. On `create()`, you can't pass `sessionConfigId` together with `toolkits`, `tools`, `tags`, `experimental.customTools`, or `experimental.customToolkits`. TypeScript reports the mix at compile time, and the SDK throws `ValidationError` before it sends a request. An empty list such as `toolkits: []` counts as set.
52 +
53 +Per-session settings stay yours: `authConfigs`, `connectedAccounts`, `manageConnections`, `sandbox`, `multiAccount`, `preload`, `sessionPreset`, `mcp`, and `experimental.assistivePrompt`.
54 +
55 +`SessionPreset.DIRECT_TOOLS` defaults to `preload: { tools: "all" }` when you omit `preload`. With a saved config, the backend resolves its policy before validating that preload. The policy must select toolkits with `enable`, enable specific tools, or enable tags within a named toolkit's tool rule. An unrestricted policy, a denylist-only policy, or top-level tags alone returns `400`. The resolved tool set must also contain at most 1,000 tools.
56 +
57 +Live verification accepted `DIRECT_TOOLS` with a saved config that provided a positive toolkit/tool scope. The no-positive-scope case was not exercised in that run; its `400` behavior is enforced by the API's preload validation. The SDK passes these API errors through unchanged.
58 +
59 +## Applying a config to an existing session
60 +
61 +Pass `sessionConfigId` in the `experimental` block of `session.update()` to replace the session's toolkit, tool, and tag access with the config's policy. Other settings are preserved.
62 +
63 +```typescript
64 +// @noErrors
65 +import { Composio } from '@composio/core';
66 +const composio = new Composio({ apiKey: 'your_api_key' });
67 +// ---cut---
68 +const session = await composio.sessions.use("session_id");
69 +
70 +await session.update({ experimental: { sessionConfigId: "sc_123" } });
71 +```
72 +
73 +The same rule applies here: `sessionConfigId` can't be combined with `toolkits`, `tools`, or `tags`, and `null` counts as set. A saved config and custom tools don't mix on update either: if the session was created with inline custom tools, the backend rejects a conflicting config with a `400`.
74 +
75 +A `409` while applying a config means the session or the config changed during the update. The SDK raises `ComposioSessionConfigConflictError`, and nothing was written: re-fetch the session with `sessions.use()` and retry.
76 +
77 +## Which config a session came from
78 +
79 +`session.experimental.sourceSessionConfig` holds `{ id }` of the last config applied to the session. The SDK sets it after `create()`, `sessions.use()`, and a successful `update()`. It stays set after later inline updates such as `update({ toolkits: [...] })`, and it's `undefined` when no config was applied. It reflects the last response this session object saw, so an update from another process leaves it stale until you call `sessions.use()` again.
80 +
81 +## When a config can't be used
82 +
83 +The SDK never retries without the config or falls back to an unrestricted session. A missing, archived, or cross-project config fails with the backend's `404`, and a project without Session configs fails with `403`. A failed `update()` leaves the session object unchanged.
docs/lib/home-navigation.ts
+2 -1
@@ -129,6 +129,7 @@ export const DOCS_PRODUCTS = {
129 '/docs/providers',
130 '/docs/how-composio-works',
131 '/docs/configuring-sessions',
132 + '/docs/session-configs',
133 '/docs/instant-tools',
134 '/docs/toolkits',
135 '/docs/authentication',
@@ -164,7 +165,7 @@ export const DOCS_PRODUCTS = {
165 links: [
166 { url: '/docs/how-composio-works', label: 'What is a Session?' },
167 { url: '/docs/configuring-sessions' },
167 -
168 + { url: '/docs/session-configs' },
169 { url: '/docs/sessions-via-mcp' },
170 ],
171 },