认证与访问
将身份、组织、成员、角色和邀请视为彼此独立的 API 责任。
API 将当前已认证用户、组织，以及被分配给单个资源的访问授权分开处理。有效登录并不代表用户已经具备某个提供商、插件、配置对象或 Worker 的访问权限。
客户端既需要有效凭据，也需要正确的组织与资源授权。这是两项拥有不同失败状态的检查。
- 01认证
通过安全客户端边界发送声明的 Bearer Session 或 Den API Key。
- 02解析身份
读取 `/v1/me` 和可用组织，再选择组织级操作。
- 03检查资源授权
通过匹配的资源 access 路由，以最窄的有效角色读取或修改授权。
- 04写入或解释
继续目标操作，或展示明确的未认证、拒绝或不可用状态。
主要接口分组
| 接口分组 | 用途 |
|---|---|
/v1/me | 读取当前用户与桌面配置。 |
/v1/me/orgs 与 /v1/org | 发现组织上下文与当前组织。 |
/v1/members/*、/v1/roles/* | 管理成员与角色分配。 |
/v1/invitations、/v1/orgs/invitations/* | 创建、预览、接受和取消邀请。 |
| OAuth 与 OpenID Discovery 路径 | 支持注册认证流程与客户端发现。 |
访问是资源级决定
多个资源都提供独立的 access 子路由，例如：
/v1/config-objects/{configObjectId}/access
/v1/plugins/{pluginId}/access
/v1/llm-providers/{llmProviderId}/access/{accessId}
/v1/skill-hubs/{skillHubId}/access
请将资源和它的授权记录视作两个独立生命周期对象。客户端应先建立组织上下文，再使用尽可能窄的资源作用域读写访问授权。
安全的客户端行为
- 不要将 bearer token 或提供商凭据保存到会话产物或日志。
- 展示组织级动作前先确认当前用户和组织。
- 对拒绝或缺失访问权限显示明确状态，而不是空资源列表。
- 调用应用中的管理操作前，始终做明确角色检查。
状态是交互模型的一部分
| 结果 | 含义 | 推荐客户端响应 |
|---|---|---|
401 | 调用方未通过当前请求的认证 | 请求新的安全 Session 或服务凭据。 |
403 | 调用方已知，但缺少需要的组织或资源授权 | 显示资源范围与下一步允许操作的负责人。 |
404 | 当前上下文无法解析请求对象 | 不要在尝试其他 ID 时泄露无关资源元数据。 |
409 | 资源处于冲突的生命周期状态 | 重新读取对象并展示真实状态，再建议用户重试。 |
凭据选择和 Base URL 行为见 OpenAPI 与集成。每个路由的授权和错误响应仍应以当前 OpenAPI Operation 为准。
认证方案、准确响应结构和当前版本的接口定义请以 packages/docs/openapi.json 为准。