API 概览¶
OpenASA API 以运行时模块分组，UI 与 Agent 调用端可以按相同边界接入。
当前公开 API 文档已按模块目录拆分，并为每个 endpoint 提供独立页面。
基础地址¶
- 生产接入基地址：
https://api.openasa.com/
本节文档中的所有路径都相对于该基地址。
模块地图¶
- Agreement：列表、详情、版本、标签、校验、评论。
- Catalog：service/flow/plugin 的列表、详情、评论。
- 我的资源（
/me）：登录态下的 service/flow 创建与修改、图片上传。 - Auth：邮箱登录、个人资料、TOTP、SSH Key，以及第三方 OAuth 登录辅助端点。
- OAuth Provider：OpenASA 对外 OAuth 能力端点（
authorize、token、userinfo、jwks、revoke）。 - CLI Auth：CLI challenge/device 登录流程接口。
- Geo/System：地理辅助接口。
鉴权边界¶
- 公共读接口：agreement/catalog/geo/system 的大多数列表与详情接口。
- 必须登录会话的接口：
/me/*- 评论写入接口（
POST .../comments） /auth/me、/auth/totp/*、/auth/ssh-keys*/cli/device/approve
浏览器场景基于 Cookie Session 鉴权。跨域前端接入时请确保 CORS 与 Allow-Credentials 配置一致。
认证模式对照¶
| 模式 | 凭证形态 | 适用场景 | 建议入口 |
|---|---|---|---|
| 浏览器会话 | Session Cookie | Web 登录与第三方 OAuth 跳转辅助流程 | Auth 模块 |
| 邮箱 Token 对 | accessToken + refreshToken |
需要显式令牌的程序调用方 | Auth 模块 |
| CLI device/challenge | 终端批准式登录链路 | asactl 与命令行场景 |
CLI 模块 |
GET /auth/userinfo 用于返回当前认证链路下的账户上下文。
GET /auth/me 用于读取或更新当前登录用户的资料记录。
错误与状态模型¶
- 常见状态码：
200、400、401、404、500，以及 IP 定位上游失败时的502。 - 错误响应通常包含：
error：机器可处理的错误标识message：面向人的错误说明
具体字段以每个端点的 OpenAPI 合同为准。
限流重点¶
- 邮箱登录相关申请/校验接口
- CLI challenge/device 接口
- 评论写入接口
调用方建议做退避重试，不要在认证链路上做高频突发重试。