Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
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.mdxindex 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">```typescriptimport { 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.mdxindex 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.mdxsimilarity index 88%rename from docs/content/reference/authentication.mdxrename to docs/content/reference/authentication/index.mdxindex e12a6aca3..7a6783adc 100644--- a/docs/content/reference/authentication.mdx+++ b/docs/content/reference/authentication/index.mdx@@ -1,5 +1,5 @@----title: Authentication+title: Overviewdescription: How to authenticate with Composio APIs using project and organization API keyskeywords: [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.jsonnew file mode 100644index 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.mdxnew file mode 100644index 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.mdxindex 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