认证 API 参考 - InsForge Docs

概述

认证 API 提供用户注册、登录、电子邮件验证、密码重置和 OAuth 集成的端点。

标头

对于已认证的函数调用：

Authorization: Bearer your-jwt-token-or-anon-key
Content-Type: application/json

对于管理员端点：

Authorization: Bearer admin-jwt-token-Or-API-Key
Content-Type: application/json

注册用户

创建新用户账户。

POST /api/auth/users

查询参数

参数	类型	必需	描述
`client_type`	string	否	客户端类型：`web`（默认）、`mobile`、`desktop` 或 `server`

请求体

字段	类型	必需	描述
`email`	string	是	用户电子邮件地址
`password`	string	是	密码（必须符合配置的要求）
`name`	string	否	用户显示名称
`redirectTo`	string	否	用于基于链接的电子邮件验证。电子邮件链接始终先打开 InsForge 后端端点；令牌验证后，InsForge 将浏览器重定向到此 URL 并显示验证结果。当 `verifyEmailMethod` 为 `link` 时需要。此 URL 必须包含在 `allowedRedirectUrls` 中。推荐：使用您的应用的登录页面。

示例（Web 客户端）

curl -X POST "https://your-app.insforge.app/api/auth/users" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "securepassword123",
    "name": "John Doe",
    "redirectTo": "http://localhost:3000/sign-in"
  }'

示例（非 Web 客户端）

curl -X POST "https://your-app.insforge.app/api/auth/users?client_type=mobile" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "securepassword123",
    "name": "John Doe",
    "redirectTo": "myapp://sign-in"
  }'

响应（Web 客户端）

{
  "user": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "email": "user@example.com",
    "emailVerified": false,
    "providers": ["email"],
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  },
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "csrfToken": "abc123...",
  "requireEmailVerification": false
}

响应（非 Web 客户端）

{
  "user": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "email": "user@example.com",
    "emailVerified": false,
    "providers": ["email"],
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  },
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
  "requireEmailVerification": false
}

对于 Web 客户端：返回 csrfToken，刷新令牌存储在 httpOnly Cookie 中。
对于 非 Web 客户端（mobile、desktop、server）：直接在响应中返回 refreshToken。安全地将其存储在您的客户端或服务器运行时中。
使用 server 用于受信任的服务器端调用者，例如 SSR 应用、BFF 或无法依赖浏览器 Cookie 的 CLI。
如果 requireEmailVerification 为 true，accessToken 和令牌将为 null，用户必须在登录前验证其电子邮件。

字段	类型	必需	描述
`method`	string	否	认证方式，默认为 `password`；邮箱 OTP 登录时使用 `otp`
`email`	string	是	用户电子邮件地址
`password`	string	密码登录时	用户密码

{
  "user": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "email": "user@example.com",
    "emailVerified": true,
    "providers": ["email"],
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  },
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "csrfToken": "abc123..."
}

响应（非 Web 客户端）

{
  "user": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "email": "user@example.com",
    "emailVerified": true,
    "providers": ["email"],
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  },
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
}

对于 Web 客户端：返回 csrfToken，刷新令牌存储在 httpOnly Cookie 中。调用 /api/auth/refresh 时在 X-CSRF-Token 标头中包含 csrfToken。
对于 非 Web 客户端（mobile、desktop、server）：直接返回 refreshToken。安全地存储它，并在调用 /api/auth/refresh 时在请求体中包含它。

邮箱 OTP 登录

当用户需要通过发送到邮箱的 6 位验证码进行免密码登录时，使用此流程。

发送登录验证码

POST /api/auth/email/send-otp

请求体

字段	类型	必需	描述
`email`	string	是	接收登录验证码的邮箱地址

curl -X POST "https://your-app.insforge.app/api/auth/email/send-otp" \
  -H "Content-Type: application/json" \
  -d '{ "email": "user@example.com" }'

该端点返回带通用消息的 202 Accepted，不会透露此邮箱是否已经属于某个用户。

使用验证码创建会话

POST /api/auth/sessions

查询参数

参数	类型	必需	描述
`client_type`	string	否	客户端类型：`web`（默认）、`mobile`、`desktop` 或 `server`

请求体

字段	类型	必需	描述
`method`	string	是	必须为 `otp`
`email`	string	是	接收验证码的邮箱地址
`otp`	string	是	6 位登录验证码
`name`	string	否	仅在验证后创建新用户时使用的资料名称

curl -X POST "https://your-app.insforge.app/api/auth/sessions?client_type=server" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "otp",
    "email": "user@example.com",
    "otp": "123456",
    "name": "Ada Lovelace"
  }'

响应使用与密码登录相同的会话结构和 client_type 行为。

验证码有效期为 5 分钟，只能使用一次，并会在三次失败尝试后失效。
InsForge 不会在发送验证码时创建用户。如果邮箱尚未注册，只会在验证成功后创建已验证的免密码用户。
为现有的未验证账户验证验证码会清除其已存储的密码，使该账户变为免密码。
如果已禁用公开注册，现有用户仍可登录。未知邮箱的有效验证码会被消费，并返回 HTTP 403。

刷新令牌

使用刷新令牌刷新访问令牌。

POST /api/auth/refresh

查询参数

参数	类型	必需	描述
`client_type`	string	否	客户端类型：`web`（默认）、`mobile`、`desktop` 或 `server`

标头（Web 客户端）

标头	类型	必需	描述
`X-CSRF-Token`	string	是	从登录/注册响应接收的 CSRF 令牌

请求体（非 Web 客户端）

字段	类型	必需	描述
`refreshToken`	string	是	从登录/注册响应接收的刷新令牌

示例（Web 客户端）

curl -X POST "https://your-app.insforge.app/api/auth/refresh" \
  -H "X-CSRF-Token: abc123..." \
  --cookie "refresh_token=..."

示例（非 Web 客户端）

curl -X POST "https://your-app.insforge.app/api/auth/refresh?client_type=mobile" \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
  }'

响应（Web 客户端）

{
  "user": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "email": "user@example.com",
    "emailVerified": true,
    "providers": ["email"],
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  },
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "csrfToken": "def456..."
}

响应（非 Web 客户端）

{
  "user": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "email": "user@example.com",
    "emailVerified": true,
    "providers": ["email"],
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  },
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
}

令牌轮换已为安全性而实现：

Web 客户端：每次刷新都返回一个新的 csrfToken，该令牌必须用于后续刷新请求。
非 Web 客户端（mobile、desktop、server）：每次刷新都返回一个新的 refreshToken。您必须持久化此新令牌并将其用于下一次刷新。在内存中更新 accessToken。

登出

登出并清除刷新令牌 Cookie。

POST /api/auth/logout

示例

curl -X POST "https://your-app.insforge.app/api/auth/logout"

响应

{
  "success": true,
  "message": "Logged out successfully"
}

获取当前用户

从 JWT 令牌获取当前已认证用户的信息。此 REST 端点不会自动刷新过期的访问令牌。

对于原始 REST 客户端，在需要时调用 POST /api/auth/refresh。
对于使用 TypeScript SDK 的浏览器应用，在启动期间调用 auth.getCurrentUser()。SDK 将在可以刷新会话时自动使用 httpOnly 刷新 Cookie。
此自动刷新行为仅限浏览器。服务器、移动和其他非浏览器客户端应显式刷新。

GET /api/auth/sessions/current

示例

curl "https://your-app.insforge.app/api/auth/sessions/current" \
  -H "Authorization: Bearer your-jwt-token"

响应

{
  "user": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "email": "user@example.com",
    "role": "authenticated"
  }
}

更新个人资料

更新当前用户的个人资料。

PATCH /api/auth/profiles/current

请求体

字段	类型	必需	描述
`profile`	object	是	个人资料数据（名称、头像 URL、自定义字段）

示例

curl -X PATCH "https://your-app.insforge.app/api/auth/profiles/current" \
  -H "Authorization: Bearer your-jwt-token" \
  -H "Content-Type: application/json" \
  -d '{
    "profile": {
      "name": "John Doe",
      "avatar_url": "https://example.com/avatar.jpg"
    }
  }'

响应

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "profile": {
    "name": "John Doe",
    "avatar_url": "https://example.com/avatar.jpg"
  }
}

获取用户个人资料

按 ID 获取用户的公开个人资料信息。

GET /api/auth/profiles/{userId}

示例

curl "https://your-app.insforge.app/api/auth/profiles/123e4567-e89b-12d3-a456-426614174000"

响应

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "profile": {
    "name": "John Doe",
    "avatar_url": "https://example.com/avatar.jpg"
  }
}

电子邮件验证

发送验证电子邮件

POST /api/auth/email/send-verification

请求体

字段	类型	必需	描述
`email`	string	是	用户电子邮件地址
`redirectTo`	string	否	用于基于链接的电子邮件验证。电子邮件链接始终先打开 InsForge 后端端点；令牌验证后，InsForge 将浏览器重定向到此 URL 并显示验证结果。当 `verifyEmailMethod` 为 `link` 时需要。此 URL 必须包含在 `allowedRedirectUrls` 中。推荐：使用您的应用的登录页面。

示例

curl -X POST "https://your-app.insforge.app/api/auth/email/send-verification" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "redirectTo": "http://localhost:3000/sign-in"
  }'

响应

{
  "success": true,
  "message": "If your email is registered, we have sent you a verification code/link."
}

验证电子邮件

POST /api/auth/email/verify

查询参数

参数	类型	必需	描述
`client_type`	string	否	客户端类型：`web`（默认）、`mobile`、`desktop` 或 `server`

请求体

字段	类型	必需	描述
`email`	string	是	用户电子邮件地址
`otp`	string	是	6 位验证码

对于基于链接的验证，电子邮件点击使用：

GET /api/auth/email/verify-link?token=...

该面向浏览器的 GET 流在后端验证令牌并重定向到存储的 redirectTo URL。POST /api/auth/email/verify 是用于 6 位代码提交的 JSON API。像这样处理浏览器重定向：

成功：?insforge_status=success&insforge_type=verify_email
错误：?insforge_status=error&insforge_type=verify_email&insforge_error=...
insforge_status：浏览器链接流的结果。对于验证，值为 success 或 error。
insforge_type：流标识符。对于验证链接，这始终是 verify_email。
insforge_error：仅当 insforge_status=error 时出现。可显示或记录的人类可读错误消息。
推荐处理：使用您的登录页面作为 redirectTo。当 insforge_status=success 时，显示确认消息并要求用户使用其电子邮件和密码登录。
如果 redirectTo 未被允许列表，InsForge 会返回 400 错误，其消息包括被拒绝的 URL，nextActions 告诉您将其添加到 allowedRedirectUrls。

示例（Web 客户端）

curl -X POST "https://your-app.insforge.app/api/auth/email/verify" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "otp": "123456"
  }'

示例（非 Web 客户端）

curl -X POST "https://your-app.insforge.app/api/auth/email/verify?client_type=mobile" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "otp": "123456"
  }'

响应（Web 客户端）

{
  "user": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "email": "user@example.com",
    "emailVerified": true
  },
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "csrfToken": "abc123..."
}

响应（非 Web 客户端）

{
  "user": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "email": "user@example.com",
    "emailVerified": true
  },
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
}

密码重置

发送重置电子邮件

POST /api/auth/email/send-reset-password

请求体

字段	类型	必需	描述
`email`	string	是	用户电子邮件地址
`redirectTo`	string	否	用于基于链接的密码重置。电子邮件链接始终先打开 InsForge 后端端点；InsForge 然后将浏览器重定向到此 URL，并在查询字符串中包含重置 `token`，以便您的应用可以呈现其自己的重置密码页面。当 `resetPasswordMethod` 为 `link` 时需要。此 URL 必须包含在 `allowedRedirectUrls` 中。推荐：使用您的应用的专用重置密码页面。

示例

curl -X POST "https://your-app.insforge.app/api/auth/email/send-reset-password" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "redirectTo": "http://localhost:3000/reset-password"
  }'

交换代码获取令牌（仅代码方法）

POST /api/auth/email/exchange-reset-password-token

请求体

字段	类型	必需	描述
`email`	string	是	用户电子邮件地址
`code`	string	是	电子邮件中的 6 位代码

示例

curl -X POST "https://your-app.insforge.app/api/auth/email/exchange-reset-password-token" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "code": "123456"
  }'

响应

{
  "token": "abc123...",
  "expiresAt": "2024-01-15T11:00:00Z"
}

重置密码

POST /api/auth/email/reset-password

对于基于链接的密码重置，电子邮件点击使用：

GET /api/auth/email/reset-password-link?token=...

该面向浏览器的 GET 流在后端验证令牌并重定向到存储的 redirectTo URL，查询字符串中包含重置令牌。POST /api/auth/email/reset-password 仍然是接受新密码的 JSON API。像这样处理浏览器重定向：

准备重置：?token=...&insforge_status=ready&insforge_type=reset_password
错误：?insforge_status=error&insforge_type=reset_password&insforge_error=...
token：仅当 insforge_status=ready 时出现。将此值作为 otp 传递给 POST /api/auth/email/reset-password。
insforge_status：浏览器链接流的结果。对于重置链接，值为 ready 或 error。
insforge_type：流标识符。对于重置链接，这始终是 reset_password。
insforge_error：仅当 insforge_status=error 时出现。可显示或记录的人类可读错误消息。
您的应用应仅在 insforge_status=ready 和 token 存在时呈现重置密码表单。

请求体

字段	类型	必需	描述
`newPassword`	string	是	新密码
`otp`	string	是	来自代码交换端点或魔法链接 URL 的重置令牌

示例

curl -X POST "https://your-app.insforge.app/api/auth/email/reset-password" \
  -H "Content-Type: application/json" \
  -d '{
    "newPassword": "newSecurePassword123",
    "otp": "abc123..."
  }'

响应

{
  "message": "Password reset successfully"
}

OAuth 认证

OAuth 认证现在使用 PKCE（代码交换证明密钥）流以增强安全性。不是直接在重定向 URL 中返回令牌，而是返回必须使用授权码交换令牌的授权码。

启动 OAuth 流

GET /api/auth/oauth/{provider}

对于在仪表板中配置的自定义提供程序，使用：

GET /api/auth/oauth/custom/{key}

查询参数

参数	类型	必需	描述
`redirect_uri`	string	是	认证后要重定向到的 URL
`code_challenge`	string	是	PKCE 代码挑战（Base64 URL 编码的代码验证器的 SHA256 哈希）
其他字符串查询参数	string	否	提供程序特定的 OAuth 提示，例如 Google 的 `prompt=select_account`

仅当额外的查询参数与服务器拥有的 OAuth 字段不冲突时，才会将其作为提供程序特定的提示转发。不要传递 client_id、redirect_uri、code_challenge、state、response_type 或 scope；InsForge/提供程序生成的值获胜，冲突的客户端值被忽略。

支持的提供程序

google
github
discord
linkedin
facebook
apple
microsoft
x
spotify
由 GET /api/auth/public-config 在 customOAuthProviders 中返回的任何自定义提供程序密钥

示例

# Generate code_verifier (random string, 43-128 characters)
CODE_VERIFIER=$(openssl rand -base64 32 | tr -d '=' | tr '/+' '_-')

# Generate code_challenge (SHA256 hash of code_verifier, Base64 URL-encoded)
CODE_CHALLENGE=$(echo -n $CODE_VERIFIER | openssl dgst -sha256 -binary | base64 | tr -d '=' | tr '/+' '_-')

curl "https://your-app.insforge.app/api/auth/oauth/google?redirect_uri=https://myapp.com/callback&code_challenge=$CODE_CHALLENGE&prompt=select_account"

# Custom provider example
curl "https://your-app.insforge.app/api/auth/oauth/custom/acme?redirect_uri=https://myapp.com/callback&code_challenge=$CODE_CHALLENGE"

响应

{
  "authUrl": "https://accounts.google.com/o/oauth2/v2/auth?client_id=..."
}

OAuth 回调

用户使用提供程序认证后，他们将被重定向到您的 redirect_uri，并带上授权码：

https://myapp.com/callback?insforge_code=abc123...

insforge_code 是一个临时授权码，必须使用 /api/auth/oauth/exchange 端点交换为令牌。

交换代码获取令牌

交换授权码获取访问令牌和刷新令牌。

POST /api/auth/oauth/exchange

查询参数

参数	类型	必需	描述
`client_type`	string	否	客户端类型：`web`（默认）、`mobile`、`desktop` 或 `server`

请求体

字段	类型	必需	描述
`code`	string	是	回调中接收的 `insforge_code`
`code_verifier`	string	是	用于生成 code_challenge 的原始 code_verifier

示例

curl -X POST "https://your-app.insforge.app/api/auth/oauth/exchange?client_type=mobile" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "abc123...",
    "code_verifier": "your-original-code-verifier"
  }'

响应

{
  "user": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "email": "user@example.com",
    "emailVerified": true,
    "providers": ["google"],
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  },
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
}

对于 Web 客户端：refreshToken 将为 null，并返回 csrfToken。刷新令牌存储在 httpOnly Cookie 中。
对于 非 Web 客户端（mobile、desktop、server）：直接返回 refreshToken。安全地存储它。

完整 OAuth 流示例（非 Web）

// 1. Generate PKCE code verifier and challenge
let codeVerifier = generateRandomString(length: 43)
let codeChallenge = sha256(codeVerifier).base64URLEncoded()

// 2. Initiate OAuth flow
let authURL = "https://your-app.insforge.app/api/auth/oauth/google" +
    "?redirect_uri=myapp://callback" +
    "&code_challenge=\(codeChallenge)"

// 3. Open browser/WebView and wait for callback
// User completes authentication...

// 4. Handle callback with insforge_code
// myapp://callback?insforge_code=abc123...

// 5. Exchange code for tokens
let response = POST("/api/auth/oauth/exchange?client_type=mobile", body: {
    "code": insforgeCode,
    "code_verifier": codeVerifier
})

// 6. Store tokens
accessToken = response.accessToken
refreshToken = response.refreshToken  // Persist securely

公开配置

获取公开认证设置（无需认证）。

GET /api/auth/public-config

示例

curl "https://your-app.insforge.app/api/auth/public-config"

响应

{
  "oAuthProviders": ["google", "github"],
  "customOAuthProviders": ["acme"],
  "requireEmailVerification": true,
  "passwordMinLength": 8,
  "requireNumber": true,
  "requireLowercase": true,
  "requireUppercase": false,
  "requireSpecialChar": false,
  "verifyEmailMethod": "code",
  "resetPasswordMethod": "link"
}

管理员端点

这些端点需要 project_admin 角色。

列出所有用户

GET /api/auth/users?offset=0&limit=10&search=john

按 ID 获取用户

GET /api/auth/users/{userId}

删除用户

curl -X DELETE "https://your-app.insforge.app/api/auth/users" \
  -H "Authorization: Bearer admin-jwt-token" \
  -H "Content-Type: application/json" \
  -d '{"userIds": ["user-id-1", "user-id-2"]}'

生成匿名令牌

POST /api/auth/tokens/anon

获取认证配置

获取当前认证设置（仅管理员）。

GET /api/auth/config

示例

curl "https://your-app.insforge.app/api/auth/config" \
  -H "Authorization: Bearer admin-jwt-token"

响应

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "requireEmailVerification": true,
  "passwordMinLength": 8,
  "requireNumber": true,
  "requireLowercase": true,
  "requireUppercase": false,
  "requireSpecialChar": false,
  "verifyEmailMethod": "code",
  "resetPasswordMethod": "link",
  "allowedRedirectUrls": ["https://myapp.com/dashboard", "https://*.myapp.com"],
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

allowedRedirectUrls 条目与完整的 redirectTo 值匹配，包括方案、主机、可选端口和路径。

精确条目必须完全匹配，例如 https://myapp.com/dashboard。
通配符仅在主机部分支持，例如 https://*.myapp.com/callback。
深层链接在明确列出时允许，例如 com.example.app:/oauth2redirect 或 myapp://auth/callback。
如果 allowedRedirectUrls 为空，InsForge 允许所有重定向以方便开发者。这对生产不安全，应在本地开发之外避免。

更新认证配置

更新认证设置（仅管理员）。

PUT /api/auth/config

请求体

字段	类型	必需	描述
`requireEmailVerification`	boolean	否	是否需要电子邮件验证
`passwordMinLength`	integer	否	最小密码长度（4-128）
`requireNumber`	boolean	否	密码中需要数字
`requireLowercase`	boolean	否	密码中需要小写字母
`requireUppercase`	boolean	否	密码中需要大写字母
`requireSpecialChar`	boolean	否	密码中需要特殊字符
`verifyEmailMethod`	string	否	电子邮件验证方法（`code` 或 `link`）
`resetPasswordMethod`	string	否	密码重置方法（`code` 或 `link`）
`allowedRedirectUrls`	array	否	允许重定向 URL 的列表。条目与完整的 `redirectTo` 值匹配。精确 URL 必须完全匹配，支持主机通配符如 `https://*.domain.com/callback`，当明确列出时允许自定义深层链接如 `com.example.app:/oauth2redirect`。如果为空，允许所有重定向，这对生产不安全。

示例

curl -X PUT "https://your-app.insforge.app/api/auth/config" \
  -H "Authorization: Bearer admin-jwt-token" \
  -H "Content-Type: application/json" \
  -d '{
    "requireEmailVerification": true,
    "passwordMinLength": 10,
    "verifyEmailMethod": "link"
  }'

交换管理员会话

交换云提供程序授权码获取管理员会话。

POST /api/auth/admin/sessions/exchange

请求体

字段	类型	必需	描述
`code`	string	是	Insforge Cloud 的授权码或 JWT

示例

curl -X POST "https://your-app.insforge.app/api/auth/admin/sessions/exchange" \
  -H "Content-Type: application/json" \
  -d '{"code": "eyJhbGciOiJIUzI1NiIs..."}'

响应

{
  "admin": {
    "sub": "cloud:user_123"
  },
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "csrfToken": "abc123..."
}

获取当前管理员会话

从项目管理员访问令牌获取当前仪表板管理员会话。

GET /api/auth/admin/sessions/current

响应

{
  "admin": {
    "sub": "local:admin"
  }
}

刷新管理员会话

刷新仪表板管理员访问令牌。此端点使用仅限仪表板的 insforge_admin_refresh_token httpOnly Cookie，不共享应用/用户刷新 Cookie。

POST /api/auth/admin/refresh

curl -X POST "https://your-app.insforge.app/api/auth/admin/refresh" \
  -H "X-CSRF-Token: abc123..." \
  --cookie "insforge_admin_refresh_token=..."

登出管理员会话

POST /api/auth/admin/logout

错误响应

无效凭据 (401)

{
  "error": "INVALID_CREDENTIALS",
  "message": "Invalid email or password",
  "statusCode": 401,
  "nextActions": "Check your email and password"
}

用户已存在 (409)

{
  "error": "USER_EXISTS",
  "message": "User with this email already exists",
  "statusCode": 409,
  "nextActions": "Use a different email or sign in"
}

电子邮件未验证 (403)

{
  "error": "EMAIL_NOT_VERIFIED",
  "message": "Please verify your email before signing in",
  "statusCode": 403,
  "nextActions": "Check your inbox for verification email"
}

⌘I

​概述

​标头

​注册用户

​查询参数

​请求体

​示例（Web 客户端）

​示例（非 Web 客户端）

​响应（Web 客户端）

​响应（非 Web 客户端）

​登录

​查询参数

​请求体

​示例（Web 客户端）

​示例（非 Web 客户端）

​响应（Web 客户端）

​响应（非 Web 客户端）

​邮箱 OTP 登录

​发送登录验证码

​请求体

​使用验证码创建会话

​查询参数

​请求体

​刷新令牌

​查询参数

​标头（Web 客户端）

​请求体（非 Web 客户端）

​示例（Web 客户端）

​示例（非 Web 客户端）

​响应（Web 客户端）

​响应（非 Web 客户端）

​登出

​示例

​响应

​获取当前用户

​示例

​响应

​更新个人资料

​请求体

​示例

​响应

​获取用户个人资料

​示例

​响应

​电子邮件验证

​发送验证电子邮件

​请求体

​示例

​响应

​验证电子邮件

​查询参数

​请求体

​示例（Web 客户端）

​示例（非 Web 客户端）

​响应（Web 客户端）

​响应（非 Web 客户端）

​密码重置

​发送重置电子邮件

​请求体

​示例

​交换代码获取令牌（仅代码方法）

​请求体

​示例

​响应

​重置密码

​请求体

​示例

​响应

​OAuth 认证

​启动 OAuth 流

​查询参数

​支持的提供程序

​示例

​响应

​OAuth 回调

​交换代码获取令牌

​查询参数

​请求体

​示例

​响应

​完整 OAuth 流示例（非 Web）

概述

标头

注册用户

查询参数

请求体

示例（Web 客户端）

示例（非 Web 客户端）

响应（Web 客户端）

响应（非 Web 客户端）

登录

查询参数

请求体

示例（Web 客户端）

示例（非 Web 客户端）

响应（Web 客户端）

响应（非 Web 客户端）

邮箱 OTP 登录

发送登录验证码

请求体

使用验证码创建会话

查询参数

请求体

刷新令牌

查询参数

标头（Web 客户端）

请求体（非 Web 客户端）

示例（Web 客户端）

示例（非 Web 客户端）

响应（Web 客户端）

响应（非 Web 客户端）

登出

示例

响应

获取当前用户

示例

响应

更新个人资料

请求体

示例

响应

获取用户个人资料

示例

响应

电子邮件验证

发送验证电子邮件

请求体

示例

响应

验证电子邮件

查询参数

请求体

示例（Web 客户端）

示例（非 Web 客户端）

响应（Web 客户端）

响应（非 Web 客户端）

密码重置

发送重置电子邮件

请求体

示例

交换代码获取令牌（仅代码方法）

请求体

示例

响应

重置密码

请求体

示例

响应

OAuth 认证

启动 OAuth 流

查询参数

支持的提供程序

示例

响应

OAuth 回调

交换代码获取令牌

查询参数

请求体

示例

响应

完整 OAuth 流示例（非 Web）