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

docs: document unattended agent authentication

Brendan O'Leary committed Sep 10, 2026 at 22:23 UTC 19c9fb2dc80fe85f17c0729a181303b5bf0b174f
7 files changed +102
docs/app/llms.txt/route.ts
+1
@@ -23,6 +23,7 @@ If it is unclear whether the goal is to integrate Composio into the application
23 - [Platform or For You](https://docs.composio.dev/docs.md): Choose between building an application and using your own connected apps.
24 - [Set up a coding agent](https://docs.composio.dev/docs/agent-setup.md): Install the Composio skill to add Composio to an existing project.
25 - [SDK quickstart](https://docs.composio.dev/docs/quickstart.md): Install Python or TypeScript packages, create a session, and run an agent.
26 +- [Authenticate an unattended agent](https://docs.composio.dev/docs/agent-setup/unattended-authentication.md): When no human is available, use \`composio login --agent\`, configure a project API key, and verify a live tool call. Human account access still requires authorization.
27 - [Native agent plugins](https://docs.composio.dev/docs/agent-plugins.md): Use your own apps from Codex or Claude Code.
28 - [Connect an MCP client](https://docs.composio.dev/docs/composio-connect.md): Connect an existing client to your apps over MCP.
29
docs/content/docs/agent-setup/index.mdx
+4
@@ -6,6 +6,10 @@ keywords: [agent setup, agent skill, claude code, codex, cursor, copilot, gemini
6
7 Install the Composio Agent Skill so your coding agent can understand your project and follow the current Platform integration path.
8
9 +<Callout type="info" title="Need an API key without a human present?">
10 +Use the supported `composio login --agent` flow. [Authenticate an unattended agent](/docs/agent-setup/unattended-authentication) covers account provisioning, application credentials, and verification with a real tool call.
11 +</Callout>
12 +
13 <AgentSetupGrid />
14
15 ## Install the skill
docs/content/docs/agent-setup/meta.json
+1
@@ -2,6 +2,7 @@
2 "title": "Agent setup",
3 "pages": [
4 "index",
5 + "unattended-authentication",
6 "clients",
7 "external:[llms.txt](/llms.txt)"
8 ]
docs/content/docs/agent-setup/unattended-authentication.mdx new
+86
@@ -0,0 +1,86 @@
1 +---
2 +title: Authenticate an unattended agent
3 +description: Obtain a Composio API key without a browser, configure your application, and verify a live tool call.
4 +keywords: [unattended, autonomous coding agent, agent login, API key, headless, signup, live verification]
5 +llmGuardrails: none
6 +---
7 +
8 +Use `composio login --agent` to create a Composio agent account and sign in without a browser or a separate email signup.
9 +
10 +<Callout type="warn" title="Only when no human is available">
11 +Use this flow for an unattended agent. When a human is available, use their existing Composio account and the [human login flow](#log-in-with-a-human) instead. Agent signup creates a separate account; it does not grant access to a human's projects or connected apps.
12 +</Callout>
13 +
14 +## Install and log in
15 +
16 +Install the [Composio CLI](/docs/cli#install), then make it available in the current shell:
17 +
18 +```bash
19 +curl -fsSL https://composio.dev/install | sh
20 +export PATH="$HOME/.local/bin:$PATH"
21 +composio login --agent
22 +composio agent whoami
23 +```
24 +
25 +The CLI reuses a saved agent identity when it is ready, or provisions one if needed. Successful login reports `account_type: "agent"`, `status: "READY"`, and `logged_in: true`. `composio agent whoami` refreshes the saved identity and reports its status, organization, and project without printing keys.
26 +
27 +If provisioning is pending, run `composio agent whoami` again later. Retry `composio login --agent` once the status is `READY`. Treat a failed login or missing credential as a blocker to live verification.
28 +
29 +Keep these constraints in mind:
30 +
31 +- The CLI refuses agent signup while signed in as a regular human user. Preserve that session and use the existing account.
32 +- `--agent` cannot be combined with `--no-browser`, `--no-wait`, `--poll`, `--key`, or `--user-api-key`. `--no-browser` alone still requires a human to open a login URL.
33 +- Network access to the installer, `agents.composio.dev`, and `backend.composio.dev` is required. Respect service errors and rate limits. Do not create repeated accounts to work around a failure.
34 +- Use the supported CLI flow. Do not reverse-engineer browser signup, create disposable inboxes, or bypass browser challenges to obtain a Composio key.
35 +
36 +## Configure the application API key
37 +
38 +The CLI saves the agent identity in `~/.composio/agent.json`, or under `COMPOSIO_CACHE_DIR` if you set it. The project's API key is the `composio.api_key` field. With `jq` installed, load it into your shell without displaying it:
39 +
40 +```bash
41 +set +x
42 +COMPOSIO_API_KEY="$(jq -er '.composio.api_key | strings | select(length > 0)' \
43 + "${COMPOSIO_CACHE_DIR:-$HOME/.composio}/agent.json")"
44 +export COMPOSIO_API_KEY
45 +: "${COMPOSIO_API_KEY:?No project API key found. Check composio agent whoami.}"
46 +```
47 +
48 +If extraction fails, stop before making API requests. Check that provisioning reached `READY` and that you are reading the same cache directory used during login.
49 +
50 +Start your application from this shell so it inherits `COMPOSIO_API_KEY`, or store the value in your application's ignored `.env` or `.env.local` file or deployment secret configuration. Check which file your environment loader reads. CLI login alone does not set the application's environment.
51 +
52 +Use `composio.api_key` for SDK calls and the REST `x-api-key` header. Do not substitute `agent_key`, `composio_agent_key`, or `composio.user_api_key`; those serve agent identity and CLI login. Keep environment files and `agent.json` out of version control, browser bundles, and logs.
53 +
54 +## Verify a live tool call
55 +
56 +First, verify the project key against a tool that needs no connected account. This example reads the public Hacker News profile for `pg`. In the shell where you exported `COMPOSIO_API_KEY`, run:
57 +
58 +```bash
59 +curl --fail-with-body --silent --show-error \
60 + https://backend.composio.dev/api/v3.1/tools/execute/HACKERNEWS_GET_USER \
61 + -H "x-api-key: $COMPOSIO_API_KEY" \
62 + -H "Content-Type: application/json" \
63 + -d '{"arguments":{"username":"pg"}}'
64 +```
65 +
66 +Check both the HTTP result and the response body. Require `successful: true`, no tool error, and profile data for the requested username. An HTTP 401, a tool schema lookup, or a successful build does not prove tool execution. A local mock verifies only the local code path.
67 +
68 +Then run the integration's own script or API route with the same project key and the intended application user ID. If the requested action needs an app account, complete its [connection flow](/docs/authentication) first. A Composio agent credential does not authorize GitHub, Slack, or another service on someone's behalf. OAuth consent, app permissions, and provider credentials still apply.
69 +
70 +For an authorized write action, verify the resulting object or state through a follow-up read or the provider's UI. Record the tool slug, sanitized result, and returned log ID if present. If only the Hacker News check succeeds, report that check separately from the requested integration action. If app authorization is unavailable, report the remaining connection step and leave the action unverified.
71 +
72 +## Log in with a human
73 +
74 +When a human is available but your terminal cannot open a browser, print a login URL:
75 +
76 +```bash
77 +composio login --no-wait
78 +```
79 +
80 +Share the URL with the human so they can sign in to their account, then complete login:
81 +
82 +```bash
83 +composio login --poll
84 +```
85 +
86 +The pending login expires after ten minutes. Run `composio login --no-wait` again if it expires. For a human account, obtain a [project API key](/reference/authenticating-to-composio#project-api-key) from the dashboard.
docs/content/docs/cli.mdx
+4
@@ -8,6 +8,10 @@ The Composio CLI gives coding agents and terminals a local tool surface. Codex,
8
9 Reach for it when you want an agent to act in your connected apps directly, without building an SDK application or configuring MCP.
10
11 +<Callout type="info" title="Unattended agent authentication">
12 +When no human is available to log in, `composio login --agent` provisions or reuses an agent account without a browser. See [Authenticate an unattended agent](/docs/agent-setup/unattended-authentication) for constraints, application API key setup, and live-tool verification.
13 +</Callout>
14 +
15 ## Install
16
17 Install the CLI with one command:
docs/content/docs/quickstart.mdx
+4
@@ -10,6 +10,10 @@ Pick your framework below. A Composio [session](/docs/how-composio-works) gives
10
11 <AgentSetupActions className="not-prose my-6" />
12
13 +<Callout type="info" title="Running as an unattended coding agent?">
14 +If no human is available to log in, use `composio login --agent` to obtain a Composio credential. Follow [Authenticate an unattended agent](/docs/agent-setup/unattended-authentication) to configure `COMPOSIO_API_KEY` and verify a live tool call.
15 +</Callout>
16 +
17 <Callout type="info">
18 The TypeScript SDK is ESM-only and requires Node.js 22.22.3 or newer. Use `import` syntax rather than CommonJS `require()`.
19 </Callout>
docs/content/reference/authenticating-to-composio/index.mdx
+2
@@ -20,6 +20,8 @@ A project API key authenticates to one project with full access. Use it for most
20
21 Get it from the dashboard: sign in to [composio.dev](https://composio.dev), open **Settings → Project Settings**, and copy the key from the **API Keys** section.
22
23 +For an unattended coding agent with no human available to log in, use the [agent authentication guide](/docs/agent-setup/unattended-authentication) to provision a Composio account with `composio login --agent`, configure a project API key, and verify a live tool call.
24 +
25 Send it in the `x-api-key` header:
26
27 ```bash