@devries-cameron20 / composio Mirror · read-only / commits / e4ec5476a
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, 19:45 UTC

add project api key permissions docs (#3532)

## Summary - Add a Project API key permissions reference page under `Reference > Authentication`. - List the routes covered by each permission area and access level. - Add stable anchor links for dashboard Learn more links, for example `/reference/authentication/project-api-key-permissions#webhooks`. - Link the new page from the Reference authentication overview and the Projects page. - Fix two existing docs build blockers that prevented local preview/build: quote SDK reference frontmatter and use `zod/v3` in the migration-guide custom tool sample. ## Validation - `bun run lint:links` - `bun run types:check` - `bun run build` - `curl -I http://localhost:3000/reference/authentication/project-api-key-permissions` returned `200` locally.

shams haroon committed Jun 8, 2026 at 17:45 UTC e4ec5476a88845c33ad99e5e1830ccdb4f190c03
6 files changed +218 -3
docs/content/docs/migration-guide/new-sdk.mdx
+1 -1
@@ -593,7 +593,7 @@ session = composio.create(
593 <Tab value="TypeScript">
594 ```typescript
595 import { Composio, experimental_createTool } from "@composio/core";
596 -import { z } from "zod";
596 +import { z } from "zod/v3";
597
598 const composio = new Composio();
599
docs/content/docs/projects.mdx
+1
@@ -96,6 +96,7 @@ You can also view and update these from **Settings > Project Settings** in the [
96
97 <Cards>
98 <Card icon={<Key />} title="Authentication" href="/docs/authentication" description="Auth configs are scoped to projects — learn how Composio manages auth" />
99 + <Card icon={<Key />} title="Project API key permissions" href="/reference/authentication/project-api-key-permissions" description="Choose scoped access levels for project API keys" />
100 <Card icon={<Database />} title="What is a session?" href="/docs/how-composio-works" description="Connected accounts and sessions live within a project" />
101 <Card icon={<Zap />} title="Triggers" href="/docs/triggers" description="Webhook configurations are project-scoped" />
102 </Cards>
docs/content/reference/authentication/index.mdx renamed
+4 -1
@@ -1,5 +1,5 @@
1 ---
2 -title: Authentication
2 +title: Overview
3 description: How to authenticate with Composio APIs using project and organization API keys
4 keywords: [API authentication, API key, x-api-key, x-org-api-key, Composio authentication, authorization]
5 ---
@@ -47,6 +47,9 @@ curl https://backend.composio.dev/api/v3.1/org/projects \
47 ```
48
49 <Cards>
50 + <Card title="Project API key permissions" href="/reference/authentication/project-api-key-permissions">
51 + Scoped project API key access levels and covered routes
52 + </Card>
53 <Card title="Errors" href="/reference/errors">
54 Understanding API error responses
55 </Card>
docs/content/reference/authentication/meta.json new
+4
@@ -0,0 +1,4 @@
1 +{
2 + "title": "Authentication",
3 + "pages": ["index", "project-api-key-permissions"]
4 +}
docs/content/reference/authentication/project-api-key-permissions.mdx new
+207
@@ -0,0 +1,207 @@
1 +---
2 +title: Project API key permissions
3 +description: Choose which project resources a scoped API key can access.
4 +keywords: [project api keys, scoped api keys, permissions, access levels]
5 +---
6 +
7 +Scoped project API keys let you choose which project resources a key can access. Use them when a key only needs a subset of your project, such as executing tools, reading logs, or managing connected accounts.
8 +
9 +Permissions are selected when the key is created and cannot be changed later. To change permissions, create a new key and rotate your application to use it.
10 +
11 +<Callout type="info">
12 +Default project API keys keep full project API key access. Scoped project API keys use the permission areas and access levels on this page.
13 +</Callout>
14 +
15 +## Access levels
16 +
17 +| Access level | What it allows |
18 +|---|---|
19 +| No access | The key cannot use routes in that permission area. |
20 +| Read only | The key can use read routes in that permission area. |
21 +| Write only | The key can use write routes in that permission area. |
22 +| Read and write | The key can use both read and write routes in that permission area. |
23 +
24 +Some read routes use `POST` because the request body carries filters or lookup input. The access level is based on what the route does, not only the HTTP method.
25 +
26 +## Permission areas
27 +
28 +Jump to each permission area to see the routes it covers.
29 +
30 +| Permission area | Available levels | Routes |
31 +|---|---|---|
32 +| Auth configs | No access, Read only, Write only, Read and write | [View routes](#auth-configs) |
33 +| Connected accounts | No access, Read only, Write only, Read and write | [View routes](#connected-accounts) |
34 +| Tools | No access, Read only | [View routes](#tools) |
35 +| Tool execution | No access, Write only | [View routes](#tool-execution) |
36 +| Proxy execute | No access, Write only | [View routes](#proxy-execute) |
37 +| Toolkits | No access, Read only, Write only, Read and write | [View routes](#toolkits) |
38 +| Triggers | No access, Read only, Write only, Read and write | [View routes](#triggers) |
39 +| Webhooks | No access, Read only, Write only, Read and write | [View routes](#webhooks) |
40 +| Observability | No access, Read only | [View routes](#observability) |
41 +| Sessions | No access, Read only, Write only, Read and write | [View routes](#sessions) |
42 +
43 +## Auth configs
44 +
45 +View and modify auth configs.
46 +
47 +| Access | Method | Endpoint |
48 +|---|---|---|
49 +| Read | `GET` | `/api/v3/auth_configs` |
50 +| Read | `GET` | `/api/v3/auth_configs/{nanoid}` |
51 +| Write | `POST` | `/api/v3/auth_configs` |
52 +| Write | `PATCH` | `/api/v3/auth_configs/{nanoid}` |
53 +| Write | `DELETE` | `/api/v3/auth_configs/{nanoid}` |
54 +| Write | `PATCH` | `/api/v3/auth_configs/{nanoid}/{status}` |
55 +
56 +## Connected accounts
57 +
58 +View and manage connected accounts.
59 +
60 +| Access | Method | Endpoint |
61 +|---|---|---|
62 +| Read | `GET` | `/api/v3/connected_accounts` |
63 +| Read | `GET` | `/api/v3/connected_accounts/{nanoid}` |
64 +| Write | `POST` | `/api/v3/connected_accounts` |
65 +| Write | `POST` | `/api/v3/connected_accounts/link` |
66 +| Write | `PATCH` | `/api/v3/connected_accounts/{nanoid}` |
67 +| Write | `PATCH` | `/api/v3/connected_accounts/{nanoid}/status` |
68 +| Write | `POST` | `/api/v3/connected_accounts/{nanoid}/refresh` |
69 +| Write | `DELETE` | `/api/v3/connected_accounts/{nanoid}` |
70 +| Write | `POST` | `/api/v3.1/connected_accounts/{nanoid}/revoke` |
71 +
72 +## Tools
73 +
74 +View tool definitions, inputs, scopes, and versions.
75 +
76 +| Access | Method | Endpoint |
77 +|---|---|---|
78 +| Read | `GET` | `/api/v3/tools` |
79 +| Read | `GET` | `/api/v3/tools/enum` |
80 +| Read | `GET` | `/api/v3/tools/{tool_slug}` |
81 +| Read | `GET` | `/api/v3/tools/{tool_slug}/get_latest_version` |
82 +| Read | `GET` | `/api/v3/tools/scopes/required` |
83 +| Read | `GET` | `/api/v3/tools/get_scopes_required` |
84 +| Read | `POST` | `/api/v3/tools/execute/{tool_slug}/input` |
85 +| Read | `GET` | `/api/v3.1/tools` |
86 +| Read | `GET` | `/api/v3.1/tools/enum` |
87 +| Read | `GET` | `/api/v3.1/tools/{tool_slug}` |
88 +| Read | `GET` | `/api/v3.1/tools/scopes/required` |
89 +| Read | `GET` | `/api/v3.1/tools/get_scopes_required` |
90 +| Read | `POST` | `/api/v3.1/tools/execute/{tool_slug}/input` |
91 +
92 +## Tool execution
93 +
94 +Execute predefined Composio tools.
95 +
96 +| Access | Method | Endpoint |
97 +|---|---|---|
98 +| Write | `POST` | `/api/v3/tools/execute/{tool_slug}` |
99 +| Write | `POST` | `/api/v3.1/tools/execute/{tool_slug}` |
100 +| Write | `POST` | `/api/v3/files/upload/request` |
101 +
102 +## Proxy execute
103 +
104 +Execute raw proxy requests against connected accounts.
105 +
106 +Proxy execute is separate from tool execution. Grant it only when your application needs to call a connected account API through the raw proxy path.
107 +
108 +| Access | Method | Endpoint |
109 +|---|---|---|
110 +| Write | `POST` | `/api/v3.1/tools/execute/proxy` |
111 +| Write | `POST` | `/api/v3/tool_router/session/{session_id}/proxy_execute` |
112 +
113 +## Toolkits
114 +
115 +View and install toolkits.
116 +
117 +| Access | Method | Endpoint |
118 +|---|---|---|
119 +| Read | `GET` | `/api/v3/toolkits` |
120 +| Read | `GET` | `/api/v3/toolkits/{slug}` |
121 +| Read | `GET` | `/api/v3/toolkits/categories` |
122 +| Read | `GET` | `/api/v3/toolkits/changelog` |
123 +| Write | `POST` | `/api/v3/toolkits/multi` |
124 +
125 +## Triggers
126 +
127 +View trigger types and manage trigger instances.
128 +
129 +| Access | Method | Endpoint |
130 +|---|---|---|
131 +| Read | `GET` | `/api/v3/triggers_types` |
132 +| Read | `GET` | `/api/v3/triggers_types/{slug}` |
133 +| Read | `GET` | `/api/v3/triggers_types/list/enum` |
134 +| Read | `GET` | `/api/v3/trigger_instances/active` |
135 +| Write | `POST` | `/api/v3/trigger_instances/{slug}/upsert` |
136 +| Write | `PATCH` | `/api/v3/trigger_instances/manage/{triggerId}` |
137 +| Write | `DELETE` | `/api/v3/trigger_instances/manage/{triggerId}` |
138 +
139 +## Webhooks
140 +
141 +View and manage webhook endpoints and subscriptions.
142 +
143 +| Access | Method | Endpoint |
144 +|---|---|---|
145 +| Read | `GET` | `/api/v3/webhook_endpoints` |
146 +| Read | `GET` | `/api/v3/webhook_endpoints/{nano_id}` |
147 +| Read | `GET` | `/api/v3/webhook_endpoints/schema` |
148 +| Read | `GET` | `/api/v3/webhook_subscriptions` |
149 +| Read | `GET` | `/api/v3/webhook_subscriptions/{id}` |
150 +| Read | `GET` | `/api/v3/webhook_subscriptions/event_types` |
151 +| Write | `POST` | `/api/v3/webhook_endpoints` |
152 +| Write | `POST` | `/api/v3/webhook_endpoints/{nano_id}` |
153 +| Write | `PATCH` | `/api/v3/webhook_endpoints/{nano_id}` |
154 +| Write | `DELETE` | `/api/v3/webhook_endpoints/{nano_id}` |
155 +| Write | `POST` | `/api/v3/webhook_subscriptions` |
156 +| Write | `PATCH` | `/api/v3/webhook_subscriptions/{id}` |
157 +| Write | `DELETE` | `/api/v3/webhook_subscriptions/{id}` |
158 +| Write | `POST` | `/api/v3/webhook_subscriptions/{id}/rotate_secret` |
159 +
160 +## Observability
161 +
162 +View execution logs and project usage summaries.
163 +
164 +| Access | Method | Endpoint |
165 +|---|---|---|
166 +| Read | `POST` | `/api/v3.1/logs/tool_execution` |
167 +| Read | `GET` | `/api/v3.1/logs/tool_execution/{id}` |
168 +| Read | `POST` | `/api/v3.1/project/usage/{entity_type}` |
169 +| Read | `POST` | `/api/v3.1/project/usage/summary` |
170 +
171 +## Sessions
172 +
173 +Create and operate sessions.
174 +
175 +| Access | Method | Endpoint |
176 +|---|---|---|
177 +| Read | `GET` | `/api/v3/tool_router/session/{session_id}` |
178 +| Read | `GET` | `/api/v3/tool_router/session/{session_id}/toolkits` |
179 +| Read | `GET` | `/api/v3/tool_router/session/{session_id}/tools` |
180 +| Read | `GET` | `/api/v3/tool_router/session/{session_id}/mounts/{mount_id}/items` |
181 +| Read | `GET` | `/api/v3.1/tool_router/session/{session_id}` |
182 +| Read | `GET` | `/api/v3.1/tool_router/session/{session_id}/config_history` |
183 +| Read | `GET` | `/api/v3.1/tool_router/session/{session_id}/tools` |
184 +| Write | `POST` | `/api/v3/tool_router/session` |
185 +| Write | `POST` | `/api/v3/tool_router/session/{session_id}/execute` |
186 +| Write | `POST` | `/api/v3/tool_router/session/{session_id}/execute_meta` |
187 +| Write | `POST` | `/api/v3/tool_router/session/{session_id}/link` |
188 +| Write | `POST` | `/api/v3/tool_router/session/{session_id}/search` |
189 +| Write | `PATCH` | `/api/v3/tool_router/session/{session_id}` |
190 +| Write | `POST` | `/api/v3/tool_router/session/{session_id}/mounts/{mount_id}/upload_url` |
191 +| Write | `POST` | `/api/v3/tool_router/session/{session_id}/mounts/{mount_id}/download_url` |
192 +| Write | `POST` | `/api/v3/tool_router/session/{session_id}/mounts/{mount_id}/delete` |
193 +| Write | `POST` | `/api/v3.1/tool_router/session` |
194 +| Write | `POST` | `/api/v3.1/tool_router/session/{session_id}/attach` |
195 +| Write | `POST` | `/api/v3.1/tool_router/session/{session_id}/execute` |
196 +| Write | `POST` | `/api/v3.1/tool_router/session/{session_id}/execute_meta` |
197 +| Write | `POST` | `/api/v3.1/tool_router/session/{session_id}/search` |
198 +| Write | `PATCH` | `/api/v3.1/tool_router/session/{session_id}` |
199 +
200 +## What to read next
201 +
202 +<Cards>
203 + <Card icon={<Key />} title="Authentication" href="/reference/authentication" description="Authenticate API requests with project and organization API keys" />
204 + <Card icon={<Key />} title="Projects" href="/docs/projects" description="Understand projects, project API keys, and project-scoped resources" />
205 + <Card icon={<Terminal />} title="Proxy execute" href="/docs/proxy-execute" description="Call connected account APIs through the raw proxy path" />
206 + <Card icon={<Monitor />} title="Observability" href="/docs/observability" description="Inspect tool execution logs and usage summaries" />
207 +</Cards>
docs/content/reference/sdk-reference/typescript/experimental.mdx
+1 -1
@@ -1,6 +1,6 @@
1 ---
2 title: Experimental
3 -description: `composio.experimental` namespace. Mirrors the Python SDK's `composio.experimental` mount, with one method per experimental surface. **Shape may change in future releases.**
3 +description: "`composio.experimental` namespace. Mirrors the Python SDK's `composio.experimental` mount, with one method per experimental surface. **Shape may change in future releases.**"
4 ---
5
6 ## Usage