# 身份认证

# 身份认证

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

## 在文档站测试

打开[登录 / API 测试](/login)，通过 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](/api/auth) 为准。

## Google OAuth

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

## 受保护请求

浏览器请求必须携带 Cookie：

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

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

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