Bedrud 文档

所有认证 endpoint 均位于 /api/auth/ 下。

概述

Bedrud 支持多种认证方式：

方式Endpoint描述
邮箱/密码POST /api/auth/login传统登录
注册POST /api/auth/register创建账户
访客POST /api/auth/guest-login临时访问
OAuthGET /api/auth/:provider/login社交登录
PasskeysPOST /api/auth/passkey/*FIDO2/WebAuthn
Token 刷新POST /api/auth/refresh续期访问令牌

Token 格式

认证成功后返回一对 JWT token：

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
}
  • Access Token - 短期有效，用于 Authorization header
  • Refresh Token - 长期有效，用于获取新的 access token

使用 Token

在所有需要认证的请求中携带 access token：

Authorization: Bearer <accessToken>

Endpoints

注册

创建新用户账户。

POST /api/auth/register

请求体：

{
  "email": "user@example.com",
  "password": "securepassword",
  "name": "John Doe"
}

响应 (200)：

{
  "accessToken": "eyJ...",
  "refreshToken": "eyJ...",
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "name": "John Doe",
    "role": "user"
  }
}

登录

使用邮箱和密码进行认证。

POST /api/auth/login

请求体：

{
  "email": "user@example.com",
  "password": "securepassword"
}

响应 (200)：

{
  "accessToken": "eyJ...",
  "refreshToken": "eyJ...",
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "name": "John Doe",
    "role": "user"
  }
}

访客登录

以访客身份加入，无需创建账户。访客拥有有限的权限。

POST /api/auth/guest-login

请求体：

{
  "name": "Guest User"
}

响应 (200)：

{
  "accessToken": "eyJ...",
  "refreshToken": "eyJ...",
  "user": {
    "id": "uuid",
    "name": "Guest User",
    "role": "guest"
  }
}

获取当前用户

获取已认证用户的个人信息。

GET /api/auth/me

Headers： Authorization: Bearer <accessToken>

响应 (200)：

{
  "id": "uuid",
  "email": "user@example.com",
  "name": "John Doe",
  "avatar": "https://...",
  "role": "user",
  "provider": "email"
}

刷新 Token

使用 refresh token 换取新的 access token。

POST /api/auth/refresh

请求体：

{
  "refreshToken": "eyJ..."
}

响应 (200)：

{
  "accessToken": "eyJ...",
  "refreshToken": "eyJ..."
}

登出

使当前 refresh token 失效。

POST /api/auth/logout

Headers： Authorization: Bearer <accessToken>

请求体：

{
  "refreshToken": "eyJ..."
}

响应 (200)：

{
  "message": "logged out"
}

OAuth 登录

通过社交提供商启动 OAuth 流程。

GET /api/auth/:provider/login

支持的提供商：

提供商路径
Google/api/auth/google/login
GitHub/api/auth/github/login
Twitter/api/auth/twitter/login

服务器会将用户重定向到提供商的授权页面。用户授权后，提供商会回调到指定 URL，服务器随后返回 JWT token。

错误响应

所有认证 endpoint 以以下格式返回错误：

{
  "error": "invalid credentials"
}
状态码含义
400请求错误（缺少字段、验证失败）
401凭据无效或 token 已过期
409邮箱已被注册
500服务器内部错误

另请参阅