ObjectOS
配置

API 访问

用于集成的自动生成 REST API、身份验证和 API 密钥。

artifact 中声明的每个对象都会通过自动生成的 REST API 对外暴露。同一套端点同时驱动 UI、集成和客户的 ETL 脚本——无需另外维护一套“集成 API”。

Base URL

https://<project-domain>/api/v1

主要入口：

Path用途
/api/v1/data/<object>每个对象自动生成的 CRUD（例如 /api/v1/data/account）
/api/v1/data/<object>/{id}读取/更新/删除单条记录
/api/v1/actions/<object>/<action>调用声明式 action（POST）
/api/v1/auth/*身份验证（登录、会话、OAuth、OIDC）
/api/v1/meta/*元数据 API（对象、字段、视图），在启用时可用
/api/v1/keys为当前调用用户生成只显示一次的 sys_api_key（POST）
/api/v1/batch跨对象事务批量写入（POST）——仅支持原子模式，每个操作都按对象门控
/api/v1/mcp通过 Streamable HTTP 提供的 Model Context Protocol 服务器——默认开启；设置 OS_MCP_SERVER_ENABLED=false 可关闭
/api/v1/health存活/就绪探针（无需身份验证）

前缀默认为 /api/v1（即 API 的 basePath /api 加上 version v1），并且可在 ObjectOS stack 上配置。

控制暴露的内容

API 暴露在 artifact 中按对象逐个治理，而不是在网关层：

  • 在对象上设置 apiEnabled: false，使其完全不出现在 REST 面上（其路由返回 404）。
  • 设置 apiMethods 白名单（例如 ['get', 'list']），将对象设为只读或以其他方式限制哪些操作可达。

两者都在 REST 层强制执行 —— 参见 REST API → 限制 API 暴露面。

同样的闸门也覆盖事务批量路由（16.0）：POST /api/v1/batch 会校验请求体，在开启事务之前就对每个操作强制执行 apiEnabled / apiMethods，update/delete 必须携带 id，无法解析的 { $ref } 父引用会被拒绝。该路由只支持原子模式——atomic: false 会被以 400 BATCH_NOT_ATOMIC 拒绝；非原子的批量写入请继续使用按对象的 createMany / updateMany 端点。

身份验证方式

调用方可以通过四种方式进行身份验证：

方式适用场景做法
Session cookie浏览器/UI 流量通过 /api/v1/auth/* 登录；cookie 的作用域限定在项目主机名
Bearer 访问令牌移动端、SPA、短时服务端任务在 /api/v1/auth/sign-in/email 用凭据换取令牌，并以 Authorization: Bearer <token> 传递
API 密钥服务器到服务器、ETL、长期存续的集成创建一条 sys_api_key 记录，作为 bearer 令牌使用
OAuth 2.1（MCP）以登录用户身份行事的 AI 代理 / MCP 客户端直接对部署本身执行自助授权码 + PKCE 流程

这些方式都会经过同一个 AuthPlugin，并最终解析为 sys_user 上下文，由 SecurityPlugin 据此评估权限和记录访问。

API 密钥

API 密钥是一等公民 sys_api_key 记录。密钥值本身以哈希形式存储——只有 prefix 和元数据保持可查询，因此即便密钥泄露也无法从数据库中还原。

签发密钥有两种方式：

  • Console——以管理员身份登录 Console → API Keys，选择所属用户， 可选地设置过期日期，并仅这一次复制显示出的密钥。

  • 自助端点——POST /api/v1/keys 为已认证的调用方生成密钥，并只返回一次 原始密钥。该密钥绑定到调用方自身的用户，因此无法用于冒充其他身份：

    curl -X POST https://app.example.com/api/v1/keys \
  -H "Authorization: Bearer <session-or-access-token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "etl-pipeline"}'
# → { "id": "...", "name": "etl-pipeline", "prefix": "os_pk_…", "key": "os_pk_live_…" }

在后续请求中，可将密钥作为 bearer 令牌、x-api-key 请求头或 Authorization: ApiKey 传递。REST 数据与元数据 API 都通过与 MCP 相同的校验器 对其认证，并以密钥所有者的权限与记录级安全运行：

curl https://app.example.com/api/v1/data/account \
  -H "x-api-key: os_pk_live_…"

要撤销某个密钥，请在对应的 sys_api_key 记录上运行 revoke_api_key action（Console UI 中也提供）。撤销会在下一次请求时立即生效。

MCP 客户端与 OAuth 2.1（ObjectStack 13+）

任何支持 OAuth 的 MCP 客户端——Claude.ai 自定义连接器、Claude Desktop、Claude Code——都可以自助接入，无需管理员签发 API 密钥：

  • 每个部署都充当自己的授权服务器（由内嵌认证实例支撑），支持 RFC 8414 / RFC 9728 发现、动态客户端注册（RFC 7591）、授权码 + PKCE，以及绑定到 <origin>/api/v1/mcp 的资源约束。要求 TLS（localhost 豁免）。
  • 用户以自己的身份登录；工具调用在其本人的权限和行级安全下运行。
  • OAuth scope 构成硬性权限上限（ObjectStack 14.5）：effective_permission = scope_ceiling ∩ user_grants。data:read 授予只读数据访问，data:write 授予完整 CRUD，能力门控的业务动作需要 actions:execute。缺少 scope 的令牌将失败关闭。

API 密钥仍作为 CI 与无头代理的并行通道——x-api-key 和 Authorization: Bearer osk_… 继续原样工作。

分页、过滤与排序

自动生成的列表端点接受标准的 ObjectStack 查询参数：

参数含义
?limit=页大小（受服务端上限约束）
?offset= 或 ?cursor=分页
?filter=使用 ObjectQL 过滤语法进行服务端过滤
?sort=排序表达式（例如 -created_at）
?fields=稀疏字段选择

完整的过滤语法请参阅框架文档——运行时语法才是权威依据。

限流

使用框架的 RateLimiter 原语（或 ingress / API 网关）应用按 IP 和按身份的限制。推荐的初始配额桶参见 Production readiness。

CORS

如果调用方在不同源的浏览器上运行，请在 ingress 或运行时中间件中配置 CORS。不要将通配符 origin 与携带凭据的请求结合使用。

OpenAPI / 发现

当镜像中包含相应能力时，运行时可以为自动生成的 REST API 提供 OpenAPI 文档。客户的集成应基于每个部署的 OpenAPI 文档生成客户端，而不是手写 URL，因为对象名称和生成的路由会跟随已部署的 artifact 而变化。

发现（discovery）还会通告 capabilities.transactionalBatch（16.0），客户端可以在连接时以声明方式探知原子批量路由是否可用，而不必靠探测 404/405/501。

Notifications

Configure how ObjectOS routes events into user inboxes — subscriptions, per-user preferences, and render templates.

Webhooks

出站 webhook 投递、签名与重试。

On this page

Base URL控制暴露的内容身份验证方式API 密钥MCP 客户端与 OAuth 2.1（ObjectStack 13+）分页、过滤与排序限流CORSOpenAPI / 发现