身份认证

CapWorks 使用 Better Auth。Web 端通过 HttpOnly Cookie 维持会话；生产环境的 Cookie 名为 __Secure-capworks-auth.session_token，使用 SameSite=Lax 和 Secure。前端代码不应读取或自行保存这个 Cookie。

在文档站测试

打开登录 / API 测试，通过 Email OTP 登录。登录成功后直接进入任意 API Reference，点击 Test 和 Send；文档站的同源代理会自动携带会话 Cookie，不需要像 Postman 一样手动填写 Token，也不能从浏览器读取 HttpOnly Cookie。

Email OTP

1. 调用 POST /api/auth/email-otp/send-verification-otp，提交邮箱和用途。
2. 用户输入 6 位验证码。
3. 调用 POST /api/auth/sign-in/email-otp 完成登录。
4. 登录后调用 POST /api/v1/account/bootstrap，选择或创建工作区并完成业务账户初始化。

验证码有效期为 10 分钟，每个邮箱每小时最多请求 5 次。具体请求结构和错误响应以 Better Auth API 为准。

Google OAuth

使用 POST /api/auth/sign-in/social 发起 Google 登录。回调由 /api/auth/callback/google 处理。原生客户端可通过 Expo/深链回到 capworks://，Web 客户端则回到受信任的 Web Origin。

受保护请求

浏览器请求必须携带 Cookie：

Code
await fetch('https://capworks-web-dev.pages.dev/api/v1/projects', {
  credentials: 'include',
});

• 401：没有有效会话，需要重新登录。
• 403：已登录，但当前工作区或项目权限不足。
• WebSocket 以关闭码 1008 结束：通常表示鉴权或访问范围不满足。

公开接口包括健康检查、认证 Provider 清单、邀请登录意图，以及按权限 Token 访问的分享和资源接口。