Skip to content

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

add project api key permissions docs (#3532)

shams haroone4ec5476a888
diff --git a/docs/content/docs/migration-guide/new-sdk.mdx b/docs/content/docs/migration-guide/new-sdk.mdx
index 6e518bc18..c436ba540 100644
--- a/docs/content/docs/migration-guide/new-sdk.mdx
+++ b/docs/content/docs/migration-guide/new-sdk.mdx
@@ -593,7 +593,7 @@ session = composio.create(
<Tab value="TypeScript">
```typescript
import { Composio, experimental_createTool } from "@composio/core";
-import { z } from "zod";
+import { z } from "zod/v3";
const composio = new Composio();
diff --git a/docs/content/docs/projects.mdx b/docs/content/docs/projects.mdx
index 5fd15fe77..63a9930a9 100644
--- a/docs/content/docs/projects.mdx
+++ b/docs/content/docs/projects.mdx
@@ -96,6 +96,7 @@ You can also view and update these from **Settings > Project Settings** in the [
<Cards>
<Card icon={<Key />} title="Authentication" href="/docs/authentication" description="Auth configs are scoped to projects — learn how Composio manages auth" />
+ <Card icon={<Key />} title="Project API key permissions" href="/reference/authentication/project-api-key-permissions" description="Choose scoped access levels for project API keys" />
<Card icon={<Database />} title="What is a session?" href="/docs/how-composio-works" description="Connected accounts and sessions live within a project" />
<Card icon={<Zap />} title="Triggers" href="/docs/triggers" description="Webhook configurations are project-scoped" />
</Cards>
diff --git a/docs/content/reference/authentication.mdx b/docs/content/reference/authentication/index.mdx
similarity index 88%
rename from docs/content/reference/authentication.mdx
rename to docs/content/reference/authentication/index.mdx
index e12a6aca3..7a6783adc 100644
--- a/docs/content/reference/authentication.mdx
+++ b/docs/content/reference/authentication/index.mdx
@@ -1,5 +1,5 @@
---
-title: Authentication
+title: Overview
description: How to authenticate with Composio APIs using project and organization API keys
keywords: [API authentication, API key, x-api-key, x-org-api-key, Composio authentication, authorization]
---
@@ -47,6 +47,9 @@ curl https://backend.composio.dev/api/v3.1/org/projects \
```
<Cards>
+ <Card title="Project API key permissions" href="/reference/authentication/project-api-key-permissions">
+ Scoped project API key access levels and covered routes
+ </Card>
<Card title="Errors" href="/reference/errors">
Understanding API error responses
</Card>
diff --git a/docs/content/reference/authentication/meta.json b/docs/content/reference/authentication/meta.json
new file mode 100644
index 000000000..bf65ae3dc
--- /dev/null
+++ b/docs/content/reference/authentication/meta.json
@@ -0,0 +1,4 @@
+{
+ "title": "Authentication",
+ "pages": ["index", "project-api-key-permissions"]
+}
diff --git a/docs/content/reference/authentication/project-api-key-permissions.mdx b/docs/content/reference/authentication/project-api-key-permissions.mdx
new file mode 100644
index 000000000..333ced622
--- /dev/null
+++ b/docs/content/reference/authentication/project-api-key-permissions.mdx
@@ -0,0 +1,207 @@
+---
+title: Project API key permissions
+description: Choose which project resources a scoped API key can access.
+keywords: [project api keys, scoped api keys, permissions, access levels]
+---
+
+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.
+
+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.
+
+<Callout type="info">
+Default project API keys keep full project API key access. Scoped project API keys use the permission areas and access levels on this page.
+</Callout>
+
+## Access levels
+
+| Access level | What it allows |
+|---|---|
+| No access | The key cannot use routes in that permission area. |
+| Read only | The key can use read routes in that permission area. |
+| Write only | The key can use write routes in that permission area. |
+| Read and write | The key can use both read and write routes in that permission area. |
+
+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.
+
+## Permission areas
+
+Jump to each permission area to see the routes it covers.
+
+| Permission area | Available levels | Routes |
+|---|---|---|
+| Auth configs | No access, Read only, Write only, Read and write | [View routes](#auth-configs) |
+| Connected accounts | No access, Read only, Write only, Read and write | [View routes](#connected-accounts) |
+| Tools | No access, Read only | [View routes](#tools) |
+| Tool execution | No access, Write only | [View routes](#tool-execution) |
+| Proxy execute | No access, Write only | [View routes](#proxy-execute) |
+| Toolkits | No access, Read only, Write only, Read and write | [View routes](#toolkits) |
+| Triggers | No access, Read only, Write only, Read and write | [View routes](#triggers) |
+| Webhooks | No access, Read only, Write only, Read and write | [View routes](#webhooks) |
+| Observability | No access, Read only | [View routes](#observability) |
+| Sessions | No access, Read only, Write only, Read and write | [View routes](#sessions) |
+
+## Auth configs
+
+View and modify auth configs.
+
+| Access | Method | Endpoint |
+|---|---|---|
+| Read | `GET` | `/api/v3/auth_configs` |
+| Read | `GET` | `/api/v3/auth_configs/{nanoid}` |
+| Write | `POST` | `/api/v3/auth_configs` |
+| Write | `PATCH` | `/api/v3/auth_configs/{nanoid}` |
+| Write | `DELETE` | `/api/v3/auth_configs/{nanoid}` |
+| Write | `PATCH` | `/api/v3/auth_configs/{nanoid}/{status}` |
+
+## Connected accounts
+
+View and manage connected accounts.
+
+| Access | Method | Endpoint |
+|---|---|---|
+| Read | `GET` | `/api/v3/connected_accounts` |
+| Read | `GET` | `/api/v3/connected_accounts/{nanoid}` |
+| Write | `POST` | `/api/v3/connected_accounts` |
+| Write | `POST` | `/api/v3/connected_accounts/link` |
+| Write | `PATCH` | `/api/v3/connected_accounts/{nanoid}` |
+| Write | `PATCH` | `/api/v3/connected_accounts/{nanoid}/status` |
+| Write | `POST` | `/api/v3/connected_accounts/{nanoid}/refresh` |
+| Write | `DELETE` | `/api/v3/connected_accounts/{nanoid}` |
+| Write | `POST` | `/api/v3.1/connected_accounts/{nanoid}/revoke` |
+
+## Tools
+
+View tool definitions, inputs, scopes, and versions.
+
+| Access | Method | Endpoint |
+|---|---|---|
+| Read | `GET` | `/api/v3/tools` |
+| Read | `GET` | `/api/v3/tools/enum` |
+| Read | `GET` | `/api/v3/tools/{tool_slug}` |
+| Read | `GET` | `/api/v3/tools/{tool_slug}/get_latest_version` |
+| Read | `GET` | `/api/v3/tools/scopes/required` |
+| Read | `GET` | `/api/v3/tools/get_scopes_required` |
+| Read | `POST` | `/api/v3/tools/execute/{tool_slug}/input` |
+| Read | `GET` | `/api/v3.1/tools` |
+| Read | `GET` | `/api/v3.1/tools/enum` |
+| Read | `GET` | `/api/v3.1/tools/{tool_slug}` |
+| Read | `GET` | `/api/v3.1/tools/scopes/required` |
+| Read | `GET` | `/api/v3.1/tools/get_scopes_required` |
+| Read | `POST` | `/api/v3.1/tools/execute/{tool_slug}/input` |
+
+## Tool execution
+
+Execute predefined Composio tools.
+
+| Access | Method | Endpoint |
+|---|---|---|
+| Write | `POST` | `/api/v3/tools/execute/{tool_slug}` |
+| Write | `POST` | `/api/v3.1/tools/execute/{tool_slug}` |
+| Write | `POST` | `/api/v3/files/upload/request` |
+
+## Proxy execute
+
+Execute raw proxy requests against connected accounts.
+
+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.
+
+| Access | Method | Endpoint |
+|---|---|---|
+| Write | `POST` | `/api/v3.1/tools/execute/proxy` |
+| Write | `POST` | `/api/v3/tool_router/session/{session_id}/proxy_execute` |
+
+## Toolkits
+
+View and install toolkits.
+
+| Access | Method | Endpoint |
+|---|---|---|
+| Read | `GET` | `/api/v3/toolkits` |
+| Read | `GET` | `/api/v3/toolkits/{slug}` |
+| Read | `GET` | `/api/v3/toolkits/categories` |
+| Read | `GET` | `/api/v3/toolkits/changelog` |
+| Write | `POST` | `/api/v3/toolkits/multi` |
+
+## Triggers
+
+View trigger types and manage trigger instances.
+
+| Access | Method | Endpoint |
+|---|---|---|
+| Read | `GET` | `/api/v3/triggers_types` |
+| Read | `GET` | `/api/v3/triggers_types/{slug}` |
+| Read | `GET` | `/api/v3/triggers_types/list/enum` |
+| Read | `GET` | `/api/v3/trigger_instances/active` |
+| Write | `POST` | `/api/v3/trigger_instances/{slug}/upsert` |
+| Write | `PATCH` | `/api/v3/trigger_instances/manage/{triggerId}` |
+| Write | `DELETE` | `/api/v3/trigger_instances/manage/{triggerId}` |
+
+## Webhooks
+
+View and manage webhook endpoints and subscriptions.
+
+| Access | Method | Endpoint |
+|---|---|---|
+| Read | `GET` | `/api/v3/webhook_endpoints` |
+| Read | `GET` | `/api/v3/webhook_endpoints/{nano_id}` |
+| Read | `GET` | `/api/v3/webhook_endpoints/schema` |
+| Read | `GET` | `/api/v3/webhook_subscriptions` |
+| Read | `GET` | `/api/v3/webhook_subscriptions/{id}` |
+| Read | `GET` | `/api/v3/webhook_subscriptions/event_types` |
+| Write | `POST` | `/api/v3/webhook_endpoints` |
+| Write | `POST` | `/api/v3/webhook_endpoints/{nano_id}` |
+| Write | `PATCH` | `/api/v3/webhook_endpoints/{nano_id}` |
+| Write | `DELETE` | `/api/v3/webhook_endpoints/{nano_id}` |
+| Write | `POST` | `/api/v3/webhook_subscriptions` |
+| Write | `PATCH` | `/api/v3/webhook_subscriptions/{id}` |
+| Write | `DELETE` | `/api/v3/webhook_subscriptions/{id}` |
+| Write | `POST` | `/api/v3/webhook_subscriptions/{id}/rotate_secret` |
+
+## Observability
+
+View execution logs and project usage summaries.
+
+| Access | Method | Endpoint |
+|---|---|---|
+| Read | `POST` | `/api/v3.1/logs/tool_execution` |
+| Read | `GET` | `/api/v3.1/logs/tool_execution/{id}` |
+| Read | `POST` | `/api/v3.1/project/usage/{entity_type}` |
+| Read | `POST` | `/api/v3.1/project/usage/summary` |
+
+## Sessions
+
+Create and operate sessions.
+
+| Access | Method | Endpoint |
+|---|---|---|
+| Read | `GET` | `/api/v3/tool_router/session/{session_id}` |
+| Read | `GET` | `/api/v3/tool_router/session/{session_id}/toolkits` |
+| Read | `GET` | `/api/v3/tool_router/session/{session_id}/tools` |
+| Read | `GET` | `/api/v3/tool_router/session/{session_id}/mounts/{mount_id}/items` |
+| Read | `GET` | `/api/v3.1/tool_router/session/{session_id}` |
+| Read | `GET` | `/api/v3.1/tool_router/session/{session_id}/config_history` |
+| Read | `GET` | `/api/v3.1/tool_router/session/{session_id}/tools` |
+| Write | `POST` | `/api/v3/tool_router/session` |
+| Write | `POST` | `/api/v3/tool_router/session/{session_id}/execute` |
+| Write | `POST` | `/api/v3/tool_router/session/{session_id}/execute_meta` |
+| Write | `POST` | `/api/v3/tool_router/session/{session_id}/link` |
+| Write | `POST` | `/api/v3/tool_router/session/{session_id}/search` |
+| Write | `PATCH` | `/api/v3/tool_router/session/{session_id}` |
+| Write | `POST` | `/api/v3/tool_router/session/{session_id}/mounts/{mount_id}/upload_url` |
+| Write | `POST` | `/api/v3/tool_router/session/{session_id}/mounts/{mount_id}/download_url` |
+| Write | `POST` | `/api/v3/tool_router/session/{session_id}/mounts/{mount_id}/delete` |
+| Write | `POST` | `/api/v3.1/tool_router/session` |
+| Write | `POST` | `/api/v3.1/tool_router/session/{session_id}/attach` |
+| Write | `POST` | `/api/v3.1/tool_router/session/{session_id}/execute` |
+| Write | `POST` | `/api/v3.1/tool_router/session/{session_id}/execute_meta` |
+| Write | `POST` | `/api/v3.1/tool_router/session/{session_id}/search` |
+| Write | `PATCH` | `/api/v3.1/tool_router/session/{session_id}` |
+
+## What to read next
+
+<Cards>
+ <Card icon={<Key />} title="Authentication" href="/reference/authentication" description="Authenticate API requests with project and organization API keys" />
+ <Card icon={<Key />} title="Projects" href="/docs/projects" description="Understand projects, project API keys, and project-scoped resources" />
+ <Card icon={<Terminal />} title="Proxy execute" href="/docs/proxy-execute" description="Call connected account APIs through the raw proxy path" />
+ <Card icon={<Monitor />} title="Observability" href="/docs/observability" description="Inspect tool execution logs and usage summaries" />
+</Cards>
diff --git a/docs/content/reference/sdk-reference/typescript/experimental.mdx b/docs/content/reference/sdk-reference/typescript/experimental.mdx
index dcd2a7452..cf7ba3dcb 100644
--- a/docs/content/reference/sdk-reference/typescript/experimental.mdx
+++ b/docs/content/reference/sdk-reference/typescript/experimental.mdx
@@ -1,6 +1,6 @@
---
title: Experimental
-description: `composio.experimental` namespace. Mirrors the Python SDK's `composio.experimental` mount, with one method per experimental surface. **Shape may change in future releases.**
+description: "`composio.experimental` namespace. Mirrors the Python SDK's `composio.experimental` mount, with one method per experimental surface. **Shape may change in future releases.**"
---
## Usage