API Gateway

核心用法

API Gateway 是 Maton 提供的统一 OAuth 代理网关，让 AI 助手能够安全调用 100+ 第三方服务 API（Google Workspace、Microsoft 365、Slack、GitHub、Notion、Airtable、HubSpot、Stripe 等）。核心工作模式为：

1. 用户授权：通过 Maton 连接流程完成目标服务的 OAuth 授权
2. 统一调用：使用 https://api.maton.ai/{app-name}/{native-api-path} 格式发起请求
3. 密钥管理：仅需 MATON_API_KEY 环境变量，OAuth 令牌由 Maton 托管不暴露给代理

典型调用示例

# 列出 Slack 频道
curl -H "Authorization: Bearer $MATON_API_KEY" \
  "https://api.maton.ai/slack/api/conversations.list?limit=10"

# 查询 HubSpot 联系人
curl -H "Authorization: Bearer $MATON_API_KEY" \
  "https://api.maton.ai/hubspot/crm/v3/objects/contacts?limit=10"

连接管理 API

• 列出连接：GET /connections?app={name}&status=ACTIVE
• 创建连接：POST /connections（返回 OAuth URL）
• 删除连接：DELETE /connections/{id}
• 多账户指定：通过 Maton-Connection Header 选择特定连接

显著优点

• 安全隔离：OAuth 令牌全程不暴露给 AI 代理，由 Maton 托管在安全基础设施中
• 极简集成：单一 API Key 管理百种服务，无需为每个服务维护独立的 OAuth 流程
• 原生 API 兼容：直接透传各服务的原生 API 路径和响应，无需学习新接口
• 细粒度授权：每个服务独立 OAuth 授权，用户可随时撤销单个连接
• 企业级覆盖：涵盖 CRM（Salesforce、HubSpot）、协作（Slack、Notion、Google Workspace）、支付（Stripe）、开发（GitHub、GitLab）等核心场景
• 多账户支持：通过 Maton-Connection Header 支持同一服务的多个账户

潜在缺点与局限性

• 网络依赖：完全依赖 Maton 云服务的可用性，无法离线使用
• 供应商锁定：API 调用必须经过 Maton 网关，迁移成本较高
• 速率限制：Maton 层限制 10 req/s，且受各服务商 API 限制叠加
• 功能边界：仅支持 REST API，部分服务的 WebSocket、实时推送能力受限
• 数据隐私：敏感业务数据流经第三方代理，需评估合规要求
• 成本不确定性：高频率调用可能产生显著费用
• 延迟增加：相比直连，增加了一次代理跳转

适合人群

• AI 自动化构建者：需要快速集成多种 SaaS 服务的代理开发者
• 无 OAuth expertise 团队：不愿自行实现 OAuth 2.0 流程和安全令牌管理的团队
• 多服务集成场景：需要一次性连接 5+ 不同 SaaS 平台的复杂工作流
• 快速原型验证：在产品早期阶段快速验证跨服务自动化可行性
• 安全敏感型企业：对 OAuth 令牌泄露风险高度警惕的组织

常规风险

• 密钥泄露：MATON_API_KEY 泄露将导致攻击者可调用用户已授权的所有服务
• OAuth 令牌过期：连接可能因用户撤销授权或令牌过期而失效
• 误操作风险：写操作（POST/PUT/DELETE）可能造成不可逆数据变更，必须二次确认
• 数据外泄：业务数据经 Maton 网关转发，存在中间人理论风险（虽使用 TLS 1.3）
• 权限扩散：用户可能授权超出实际需求范围的 OAuth scope