学习笔记 · Obsidian
Smith API：API Key、登录 SSO、审计与 Marketplace
Smith API 的主机是 https://api.smith.langchain.com。常规 API 以 X-Api-Key、Tenant/Organization 上下文或 Bearer session 鉴权；OpenAPI 的 security 数组表示“其中任一方案”，并不代表可同时忽略资源作用域。公开 SSO/OIDC discovery 等端点明确为 security: []，只能返回完成认证所必需的最小信息。
API Key 与 PAT
旧的 /api/v1/api-key 族提供创建、列表、删除 API key：
| 操作 | 方法与路径 | 关键字段 |
|---|---|---|
| 创建 | POST /api/v1/api-key | description、read_only、expires_at、workspaces、role_id、org_role_id、default_workspace_id |
| 列表 | GET /api/v1/api-key | 返回 metadata，不返回完整 key |
| 删除 | DELETE /api/v1/api-key/{api_key_id} | UUID path |
创建响应在 APIKeyCreateResponse.key 只给出完整 secret；常规响应只有 short_key、last used、expiry、workspace/role 信息。必须在创建时立即进入 secret manager，之后不能依赖 list 取回。
/api/v1/api-key/current 的 create/list/delete PAT 三个入口已标记 deprecated，替代入口是 /api/v1/orgs/current/personal-access-tokens。新集成不要继续绑定 deprecated path；迁移时保留旧 client 的读写兼容窗口，并对照响应 schema 后再切换。
生产 key 基线：
- 默认过期而不是永久 key；使用 workspace 与 role 最小作用域；只读任务设
read_only=true。 - 不在浏览器、URL、日志、trace input/output 或 notebook 中存 token。
- 轮换采用“新建 → 双 key 验证 → 切换 → 删除旧 key”，删除前查
last_used_at。 - API key ID、short key 和 secret 是不同字段；审计记录 ID/short key，不记录完整 secret。
登录与 SSO 发现
SSO 相关公开流程：
| 端点 | 鉴权 | 用途 |
|---|---|---|
POST /api/v1/login | public | 登录入口 |
GET /api/v1/sso/settings/{sso_login_slug} | public | 由 login slug 返回 provider/organization 摘要 |
POST /api/v1/sso/email-lookup | public | 为 SCIM-provisioned email 查可用 SSO provider |
POST /api/v1/sso/email-verification/status | public | email + SAML provider ID 查确认时间 |
POST /api/v1/sso/email-verification/confirm | public | 用一次性 token 确认邮箱 |
POST /api/v1/sso/email-verification/send | Bearer | 发送确认邮件 |
GET /auth/public | workspace session | 返回当前 session 的 user/org/tenant IDs 与 email |
公开不等于无限制：email lookup/status/send 必须限流、防枚举、统一错误文案、短期一次性 token 与重放保护。/auth/public 名字包含 public，但 OpenAPI 要 API Key/Tenant/Bearer 之一；它只是“公开认证信息结构”，不是匿名接口。
Login/SSO client 不能只信前端传来的 organization、workspace 或 email。身份与资源关联必须在服务端从验证后的 session、SAML/OIDC claims 和组织配置解析。
当前 Organization 安全配置快照
GET /api/v1/platform/orgs/current/info 使用 Organization 上下文，返回的管理快照包含：
- SSO/JIT/invite/public sharing/PAT creation 开关；
- permissions、tier、workspace 上限、成员禁用状态；
- key/PAT/service key 最大有效期；
- SCIM group separator、security contact；
- IP allowlist 与是否启用；
- disabled model providers；
- LLM auth proxy 开关、audience 与 allowed URLs；
- managed eval consent、Engine enable 与月 LCU spend limit；
- BYOC、Marketplace payout 等 feature flags。
这是控制面状态，不应用作客户端长期缓存。管理 UI 应按 permission 隐藏/禁用操作，服务端仍必须逐请求授权；配置变更需记录旧值、新值、操作者与回滚计划。
OCSF Audit Logs
GET /api/v1/audit-logs 按 organization 返回 OCSF API Activity（Class UID 6003），适合 SIEM。start_time 与 end_time 都必填且 inclusive；可按 workspace、operations 过滤，limit 1–100（默认 10），用 base64 JSON cursor 分页。
游标不应由客户端解码后篡改；日志采集要保存 checkpoint，处理重复页和超时重试。审计日志含敏感身份/操作上下文，导入 SIEM 时继续执行访问控制、保留期、加密与脱敏。
AWS Marketplace 注册
POST /aws-marketplace/register 是 public multipart endpoint，接收必填 x-amzn-marketplace-token，解析 Marketplace customer 并写库，成功以 303 跳到 thank-you 页面；错误为 400/500。
该 token 必须服务端向 AWS 验证，不能信任表单值。需要防 CSRF/重放、限制 body、记录 AWS customer 与 organization 绑定的幂等键，并只允许预配置 redirect 目标，避免 open redirect。
错误与验证
OpenAPI 常见 422 是参数/schema 验证失败；OAuth/Go 路由还会明确给 400/401/403/404/5xx。客户端不要把所有非 2xx 解析成同一 JSON schema。日志与重试策略：
- 400/401/403/422：修请求或权限，不自动无限重试；
- 404：同时可能代表不存在、越权隐藏或已删除；
- 429/5xx/网络失败：只对幂等读取或有 idempotency key 的写操作做有界退避；
- 创建 secret/token 的响应若客户端超时，先查资源列表，不能盲目重建一批凭据。