Sign Up as an Agent

Agents can sign up for Composio directly through agents.composio.dev without a human creating an account first. The flow creates an agent identity, returns Composio credentials, and gives the agent a ready-to-run CLI install/login command.

The base URL for all endpoints on this page is:

https://agents.composio.dev

Flow

Check for an existing identity. Before signing up, look for ~/.composio/anonymous_user_data.json. If it exists, read the saved agent_key and call GET /api/whoami with Authorization: Bearer <agent_key>. If it returns 200 with status: "READY", reuse the saved credentials.
Sign up. Call POST /api/signup. By default, the endpoint waits until the account is ready and returns a 201 response containing the agent_key plus Composio credentials (member_id, org_id, project_id, api_key, and user_api_key). Save the full response to ~/.composio/anonymous_user_data.json immediately so future runs do not create a new identity.
Install and log in to the CLI. Call GET /api/cli with the agent_key. It returns paste-ready install and login commands.
Optionally claim the org. Call POST /api/claim with a human email only when you want to hand the organization over to a human admin.

POST /api/signup creates an agent email inbox, starts the Composio signup flow, and long-polls for up to 120 seconds. Most calls complete in about 5–10 seconds.

mkdir -p ~/.composio

curl -sS -X POST 'https://agents.composio.dev/api/signup' \
  -H 'content-type: application/json' \
  -d '{}' \
  -o ~/.composio/anonymous_user_data.json

cat ~/.composio/anonymous_user_data.json

Successful response:

{
  "status": "ready",
  "request_id": "req_xxx",
  "slug": "amber-cedar-otter",
  "email": "amber-cedar-otter@agent.composio.ai",
  "agent_key": "composio_agent_key_xxx",
  "composio": {
    "member_id": "uuid",
    "org_id": "org_xxx",
    "project_id": "proj_xxx",
    "api_key": "ak_xxx",
    "user_api_key": "uak_xxx"
  }
}

If the 120-second wait expires, the endpoint returns 202 with status: "pending". Poll GET /api/whoami until the status is READY.

{
  "status": "pending",
  "request_id": "req_xxx",
  "slug": "amber-cedar-otter",
  "email": "amber-cedar-otter@agent.composio.ai",
  "agent_key": "composio_agent_key_xxx",
  "poll": "/api/whoami"
}

To skip waiting and poll yourself, pass ?wait=0:

curl -sS -X POST 'https://agents.composio.dev/api/signup?wait=0' \
  -H 'content-type: application/json' \
  -d '{}'

Verify a saved identity

Use GET /api/whoami to verify a saved agent_key and fetch the current Composio credentials. The agent_key authenticates only against the agent signup surface; it is not your Composio API key.

AGENT_KEY="$(jq -r '.agent_key' ~/.composio/anonymous_user_data.json)"

curl -sS 'https://agents.composio.dev/api/whoami' \
  -H "Authorization: Bearer ${AGENT_KEY}"

Response:

{
  "slug": "amber-cedar-otter",
  "email": "amber-cedar-otter@agent.composio.ai",
  "status": "READY",
  "claimed_by": null,
  "claimed_at": null,
  "composio": {
    "member_id": "uuid",
    "org_id": "org_xxx",
    "project_id": "proj_xxx",
    "api_key": "ak_xxx",
    "user_api_key": "uak_xxx"
  }
}

Install the CLI

GET /api/cli returns install and login commands with the agent's user_api_key and org_id already filled in.

AGENT_KEY="$(jq -r '.agent_key' ~/.composio/anonymous_user_data.json)"

curl -sS 'https://agents.composio.dev/api/cli' \
  -H "Authorization: Bearer ${AGENT_KEY}"

Example response:

Install Composio CLI using this command:
curl -fsSL https://composio.dev/install | bash

Then log in using this command:
composio login --user-api-key "uak_..." --org "ok_..."

Run the returned commands to install and authenticate the CLI.

Claim the organization

Claiming is optional. Use it only when the agent wants to invite a human admin to take over the Composio organization. The endpoint issues a single-use admin invite that expires after 24 hours.

AGENT_KEY="$(jq -r '.agent_key' ~/.composio/anonymous_user_data.json)"

curl -sS -X POST 'https://agents.composio.dev/api/claim' \
  -H "Authorization: Bearer ${AGENT_KEY}" \
  -H 'content-type: application/json' \
  -d '{"email":"human@example.com"}'

Response fields can vary by backend/CLI version. Treat status, email, and org_id as the stable fields:

{
  "status": "invited",
  "email": "human@example.com",
  "org_id": "org_xxx",
  "invite_code": null,
  "claim_slug": "claim_xxx",
  "expires_at": "2026-05-19T00:00:00.000Z"
}

status: "invited" means the claim request was accepted and an invite record was created. It does not by itself prove that the email was delivered or accepted by the human.
invite_code may be null in CLI responses. Do not treat a null invite code as failure if status is "invited".
claim_slug is an opaque claim identifier. Keep it redacted in logs and support tickets unless Composio support explicitly asks for it.
expires_at, when present, tells you when the claim invitation expires.

To verify safely without printing secrets:

curl -sS -X POST 'https://agents.composio.dev/api/claim' \
  -H "Authorization: Bearer ${AGENT_KEY}" \
  -H 'content-type: application/json' \
  -d '{"email":"human@example.com"}' \
  | jq '{
      status,
      email,
      org_id_present: (.org_id != null),
      invite_code_present: (.invite_code != null),
      claim_slug_present: (.claim_slug != null),
      expires_at_present: (.expires_at != null)
    }'

Claim troubleshooting

Missing email locally — /composio-claim and similar helpers require a target email. If omitted, provide one and retry.
No email received — first confirm the API response has status: "invited" and the correct email. Then check spam/quarantine and retry the claim after a few minutes. If the invite still does not arrive, use the dashboard or contact support with redacted field-presence output.
invite_code: null — this can be normal for CLI responses. Look for status: "invited", org_id, and, if present, claim_slug/expires_at.
Cloudflare or upstream 5xx — retry later. A 502 from agents.composio.dev indicates upstream service instability, not a local request-shape error.

Read the agent inbox

Each agent gets an email address at <slug>@agent.composio.ai. Use GET /api/mail to list messages for the agent inbox.

AGENT_KEY="$(jq -r '.agent_key' ~/.composio/anonymous_user_data.json)"

curl -sS 'https://agents.composio.dev/api/mail?limit=50' \
  -H "Authorization: Bearer ${AGENT_KEY}"

Response:

{
  "count": 1,
  "messages": [
    {
      "id": "msg_xxx",
      "thread_id": "thr_xxx",
      "from": "no-reply@composio.dev",
      "to": "amber-cedar-otter@agent.composio.ai",
      "subject": "Sign in to Composio",
      "preview": "Click the link below to sign in...",
      "received_at": "2026-04-13T22:00:00.000Z"
    }
  ]
}

Agent keys

Agent keys are prefixed with composio_agent_key_ and are only valid for these endpoints:

GET /api/whoami
GET /api/mail
GET /api/cli
POST /api/claim

Use the real Composio API key from the composio.api_key field when calling Composio APIs and SDKs.

Sign Up as an Agent

On this page