SaaS Gateway (saas-gateway) 🔌

Unified SaaS integration gateway (v3.1) for autonomous agents. Powered by AISA.

One API key. Connect third-party SaaS apps and run tools through the AISA gateway (api.aisa.one).

Compatibility

Works with any agentskills.io-compatible harness, including:

• Claude Code and Claude (Anthropic)
• OpenAI Codex
• Cursor
• Gemini CLI (Google)
• OpenCode, Goose, OpenClaw, Hermes
• and any other harness that implements the Agent Skills specification

Requires curl and AISA_API_KEY (get one at aisa.one).

When to use

• Integrate Gmail, Slack, GitHub, or other third-party SaaS toolkits via api.aisa.one
• Create OAuth links, list connected accounts, or refresh credentials
• Discover and execute SaaS tools or tool-router sessions
• Manage triggers and webhooks (with user confirmation for writes)
• Create and manage MCP servers for session-scoped tool access
• Upload/download files, check usage statistics, or manage projects

When NOT to use

• The user needs direct access to the upstream provider's API without going through the AISA gateway
• The task only needs generic web search (use a search skill instead)
• No AISA_API_KEY is available

Quick Start

Linux / macOS:

export AISA_API_KEY="your-key"

Windows (PowerShell):

$env:AISA_API_KEY = "your-key"

All requests use:

• Base URL: https://api.aisa.one
• Path prefix: /apis/v1/composio/... (literal AISA gateway path — do not modify)
• Auth header: Authorization: Bearer $AISA_API_KEY

Windows note: Use curl.exe instead of curl in PowerShell (the built-in curl is an alias for Invoke-WebRequest and has different syntax). Or use CMD rather than PowerShell.

Replace {param} in paths with real IDs from previous responses. Never use mock IDs like test_nanoid_001 in production.

What Can You Do?

"Check my AISA project session and list auth configs for GitHub"
"Create an OAuth link so user alice can connect Slack"
"Run the GitHub create-issue tool for a connected account"
"List active triggers and webhook subscriptions"
"Set up an MCP server so my agent can use GitHub tools in a session"
"Upload a file and check my project usage this month"

Intent → Workflow Quick Reference (Agent Entry Point)

Map the user's request to a workflow before reading further:

When intent is unclear, run Workflow 1 to confirm session context, then ask the user what they need.

Core Workflows

1. Verify session and project context

curl "https://api.aisa.one/apis/v1/composio/auth/session/info" \
  -H "Authorization: Bearer $AISA_API_KEY"

Key fields: project, org_member, api_key (nested IDs may appear under api_key).

If the user also asks for auth configs (e.g. GitHub), in the same flow:

curl "https://api.aisa.one/apis/v1/composio/auth_configs?toolkit_slug=github&limit=10" \
  -H "Authorization: Bearer $AISA_API_KEY"

Use: items[].id as auth_config_id for OAuth linking.

Details: references/auth_and_session.md

2. Connect a user to a third-party app (OAuth)

1. GET /apis/v1/composio/auth_configs?toolkit_slug={slug} — find items[].id as auth_config_id
   • If empty: ask the user whether to create an auth config, then POST /apis/v1/composio/auth_configs with {"toolkit": {"slug": "{slug}"}, "auth_config": {"type": "use_composio_managed_auth"}} — use auth_config.id from response as auth_config_id
2. Confirm with user before POST /apis/v1/composio/connected_accounts/link — body: auth_config_id, user_id (email or arbitrary string, e.g. alice@example.com); callback_url is optional
3. Send the user to redirect_url from the response — the human must open this URL in a browser to complete OAuth
4. Poll GET /apis/v1/composio/connected_accounts?user_ids={user_id}&toolkit_slugs={slug} until status is no longer PENDING
   • Poll interval: wait 3–5 seconds between checks, up to ~2 minutes
   • Possible statuses: ACTIVE (connected), PENDING (user has not completed OAuth yet), DISCONNECTED / REVOKED (link failed or expired)
   • If still PENDING after 2 minutes, tell the user the link may have expired and offer to create a new link
5. On success, save items[].id (nanoid) as connected_account_id for tool execution

If an ACTIVE connection already exists: If GET connected_accounts already returns an ACTIVE connection for the given user_id + toolkit_slug, reuse that connected_account_id directly — no re-OAuth needed. Only create a new link when the user explicitly requests re-authorization (the old link is not automatically removed; ask the user whether to keep it).

Details: references/connect_account.md

3. Discover and execute tools

Direct execution (one-off tool call):

1. Resolve connected_account_id:
   • User already connected → GET /apis/v1/composio/connected_accounts?toolkit_slugs={slug} (add user_ids= if multiple accounts exist) and use items[].id
   • Not connected → run Workflow 2 first
2. Find the tool slug:
   • GET /apis/v1/composio/tools?toolkit_slug={slug} — map user intent (e.g. "create issue") to actual items[].slug (e.g. GITHUB_CREATE_AN_ISSUE)
   • Never guess tool_slug — always list tools first if unsure
3. Get the tool's argument schema:
   • GET /apis/v1/composio/tools/{tool_slug} — inspect input_parameters.required (mandatory fields) and input_parameters.properties (all fields with types and descriptions)
   • Alternatively, use natural-language input generation: POST /apis/v1/composio/tools/execute/{tool_slug}/input with {"text": "Create an issue titled Hello in my-org/my-repo"} — may return error code: 1010 on restricted tiers, in which case use the schema from GET /tools/{tool_slug} instead
4. Confirm with user before POST /apis/v1/composio/tools/execute/{tool_slug} — body requires:
   • connected_account_id: from step 1
   • entity_id: the user identifier string (same value used as user_id when linking the account, e.g. alice@example.com)
   • arguments: matching the tool's input_parameters schema
5. Check the response: successful field indicates if the tool call worked. If successful is false, inspect error or data for details and retry with corrected arguments

Tool router (session-scoped, MCP-style access):

Use tool router when you need a persistent session for multiple tool calls, or when building an MCP integration.

1. POST /apis/v1/composio/tool_router/session — body: {"user_id": "user-id", "toolkits": ["github"]}
2. Save session_id from the response
3. Search for tools: POST .../tool_router/session/{session_id}/search — body: {"query": "create issue"}
4. List available tools: GET .../tool_router/session/{session_id}/tools
5. Confirm with user before POST .../tool_router/session/{session_id}/execute — body: {"tool_slug": "GITHUB_CREATE_AN_ISSUE", "arguments": {...}}
6. Other session operations:
   • GET .../session/{session_id} — check session status
   • GET .../session/{session_id}/toolkits — list session's toolkits
   • POST .../session/{session_id}/link — add a toolkit connection to the session
   • POST .../session/{session_id}/proxy_execute — raw HTTP proxy within session
   • GET .../session/{session_id}/config_history — view past config changes

Details: references/execute_tools.md

4. Triggers and webhooks (read-first)

1. GET /apis/v1/composio/trigger_instances/active — list active triggers (read-only, no confirmation needed)
2. GET /apis/v1/composio/triggers_types — browse available trigger types
3. Confirm with user before any create/update/delete on triggers or webhook subscriptions
4. GET /apis/v1/composio/webhook_endpoints — list registered webhook URLs
5. GET /apis/v1/composio/webhook_subscriptions — list active subscriptions
6. GET /apis/v1/composio/webhook_subscriptions/event_types — see available event types before creating a subscription

Details: references/triggers_webhooks.md

5. MCP servers

Create and manage MCP (Model Context Protocol) servers for agent tool access.

1. List existing MCP servers: GET /apis/v1/composio/mcp/servers (optional: category, search filters)
2. Create an MCP server for a single app: Confirm with user, then POST /apis/v1/composio/mcp/servers — body: {"app": {"slug": "github"}, "name": "My GitHub MCP"}
3. Create a custom MCP server with multiple apps: Confirm with user, then POST /apis/v1/composio/mcp/servers/custom — body: {"apps": [{"slug": "github"}, {"slug": "slack"}], "name": "My Multi-App MCP"}
4. Generate an MCP URL: POST /apis/v1/composio/mcp/servers/generate — produces a connection URL for the agent
5. Manage instances: GET /apis/v1/composio/mcp/servers/{serverId}/instances, POST ... to create, DELETE .../instances/{instanceId} to remove
6. Get/update/delete a server: GET/PATCH/DELETE /apis/v1/composio/mcp/{id}

Details: references/endpoint_catalog.md (group: mcp)

6. Files, projects, and usage

Files:

• List uploaded files: GET /apis/v1/composio/files/list?limit=10
• Upload: POST /apis/v1/composio/files/upload/request — get a presigned S3 URL, then PUT the file content to that URL

Projects:

• List projects: GET /apis/v1/composio/org/owner/project/list
• Create project: Confirm with user, then POST /apis/v1/composio/org/owner/project/new
• Get/update/delete: GET/DELETE /apis/v1/composio/org/owner/project/{nano_id}
• Regenerate API key: Confirm with user, then POST /apis/v1/composio/org/owner/project/{nano_id}/regenerate_api_key

Usage statistics:

• Org-level summary: POST /apis/v1/composio/org/usage/summary — body: {}
• Org-level breakdown by entity: POST /apis/v1/composio/org/usage/{entity_type} — common {entity_type} values: tool_calls, sessions; body accepts group_by, limit, order_by, order_direction
• Project-level: POST /apis/v1/composio/project/usage/summary — body: {}; POST /apis/v1/composio/project/usage/{entity_type} — same fields as above

Response: Usage summary root field is entities (contains tool_calls and sessions sub-objects); breakdown root field is groups (aggregated by the group_by dimension)

Tool execution logs:

• Search logs: POST /apis/v1/composio/logs/tool_execution — body: {"limit": 10}; response root field is logs (not items), pagination key is next_cursor
• Get single log: GET /apis/v1/composio/logs/tool_execution/{id}
• Key log entry fields: metadata.tool.slug, metadata.user_id, metadata.connected_account_id, metrics.duration_ms, status (success/error)

Details: references/execute_tools.md (logs section), references/mcp_projects_usage.md (usage section)

Reference routing

Lookup order: intent → reference (curl examples) → endpoint_catalog.md → upstream API docs for semantics only. Request URLs must use AISA inner_uri paths.

Path parameters

Important: Use the exact casing shown in the endpoint path. The API is case-sensitive.

Safety

• Confirm with the user before POST / PATCH / DELETE that change production data (including connected_accounts/link, tools/execute, tool_router/session/{id}/execute, MCP server create/delete, auth config create/update, trigger upsert/delete, webhook create/delete)
• DELETE may soft-delete configs, connections, or webhooks
• OAuth redirect_url must be opened by a human in a browser
• Read-only GET calls (session, list configs, list tools) do not require confirmation unless the user asked you to avoid network calls
• Rate limiting: if you receive 429 responses, wait briefly and retry. Avoid rapid-fire API calls in loops without delays

Troubleshooting