API 参考：认证与用户

提供注册、登录、令牌刷新、个人资料和邀请处理接口。认证要求随接口而异，公开接口在各条目中标注。

除特别标注外，本组接口在认证中间件之后仅要求“已登录”（无角色下限）。免认证接口见各条目。

认证（/api/v1/auth）

POST /api/v1/auth/register

用途：注册新用户（自助注册模式）。免认证。Handler: internal/handler/auth.go

字段	类型	必填	说明
`username`	string	是（`binding:"required"`）	用户名
`email`	string	是（`binding:"required"`）	邮箱
`password`	string	是（`binding:"required"`）	密码
`tenant_provisioning`	string	否	空间开通策略

响应：201 {"success":true,"message":"...","user":{User}}

bash

curl -X POST $BASE/api/v1/auth/register -H 'Content-Type: application/json' \
  -d '{"username":"alice","email":"a@ex.com","password":"secret123"}'

POST /api/v1/auth/register-by-invite

用途：通过邀请/分享链接 token 注册并加入空间。免认证，IP 限流 30 次/分钟。Handler: internal/handler/auth_register_by_invite.go

字段	类型	必填	说明
`token`	string	是（`binding:"required"`）	邀请 token
`email`	string	是（`binding:"required,email"`）	邮箱
`username`	string	是（`binding:"required"`）	用户名
`password`	string	是（`binding:"required,min=6"`）	密码（8–32 位，字母+数字；复杂模式另需大小写和特殊字符）

响应：201，同 Login（user/active_tenant/memberships/token/refresh_token）。

bash

curl -X POST $BASE/api/v1/auth/register-by-invite -H 'Content-Type: application/json' \
  -d '{"token":"<invite_token>","email":"a@ex.com","username":"alice","password":"secret123"}'

POST /api/v1/auth/invitations/lookup

用途：匿名查询邀请 token 对应的空间信息（注册前预览）。免认证，IP 限流。Handler: internal/handler/auth_register_by_invite.go

字段	类型	必填	说明
`token`	string	是（`binding:"required"`）	邀请 token

响应：200 {"success":true,"data":{"tenant_id","tenant_name","role","expires_at"}}

bash

curl -X POST $BASE/api/v1/auth/invitations/lookup -H 'Content-Type: application/json' -d '{"token":"<invite_token>"}'

用途：邮箱密码登录。免认证。Handler: internal/handler/auth.go

字段	类型	必填	说明
`email`	string	是（`binding:"required"`）	邮箱
`password`	string	是（`binding:"required"`）	密码

响应：200 {"success":true,"user":{...},"active_tenant":{...},"memberships":[...],"token":"...","refresh_token":"..."}

bash

curl -X POST $BASE/api/v1/auth/login -H 'Content-Type: application/json' -d '{"email":"a@ex.com","password":"secret123"}'

POST /api/v1/auth/auto-setup

用途：一键初始化（本地/Lite 场景自动建号建空间）。免认证，无请求体。Handler: internal/handler/auth.go

响应：200，同 Login。

bash

curl -X POST $BASE/api/v1/auth/auto-setup

GET /api/v1/auth/config

用途：查询注册模式等认证配置。免认证。Handler: internal/handler/auth.go

响应：200 {"success":true,"registration_mode":"self_serve|invite_only","complex_password_enabled":false}

bash

curl $BASE/api/v1/auth/config

POST /api/v1/auth/switch-tenant

用途：切换当前活跃空间并换发 token。需登录（无空间也可调用）。Handler: internal/handler/auth.go

字段	类型	必填	说明
`tenant_id`	uint64	是（`binding:"required"`）	目标空间 ID
`refresh_token`	string	否	用于换发新 token

响应：200，同 Login。

换签成功会把目标空间写入账号级「最近活跃租户」偏好，下次登录（密码/OIDC/换设备）与 refresh 都回到该空间。refresh JWT 不含 tenant_id，因此偏好写入失败则整次换签失败、不会发出新 token。API 客户端无需再补发 PUT /auth/me/preferences。Web UI 切空间不走本接口。一次换签会改变该用户所有设备的下次落点。

bash

curl -X POST $BASE/api/v1/auth/switch-tenant -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"tenant_id":2}'

GET /api/v1/auth/oidc/config

用途：查询 OIDC 是否启用及显示名。免认证。Handler: internal/handler/auth.go

响应：200 {"success":true,"enabled":bool,"provider_display_name":"..."}

bash

curl $BASE/api/v1/auth/oidc/config

GET /api/v1/auth/oidc/start

免登录，直接返回 302 和指向 IdP 的 Location，可供企业门户链接使用。无需先请求 JSON 授权地址；回调由请求 origin 构造为 /api/v1/auth/oidc/callback。回调后的登录结果与原 OIDC 链路一致。

bash

curl -i "$BASE/api/v1/auth/oidc/start"

GET /api/v1/auth/oidc/url

用途：获取 OIDC 授权跳转 URL。免认证。Handler: internal/handler/auth.go

查询参数	类型	必填	说明
`redirect_uri`	string	是	回调地址

响应：200 {"success":true,"authorization_url":"...","nonce":"..."}

bash

curl "$BASE/api/v1/auth/oidc/url?redirect_uri=https://app.example.com/callback"

GET /api/v1/auth/oidc/callback

用途：OIDC 授权回调（浏览器重定向进入）。免认证。Handler: internal/handler/auth.go

查询参数：code、state、error、error_description（均由 OIDC 提供方带回）。

响应：302 重定向到前端，成功携带 #oidc_result=<base64url>，失败携带 #oidc_error=...。

bash

curl -i "$BASE/api/v1/auth/oidc/callback?code=xxx&state=yyy"

POST /api/v1/auth/refresh

用途：用 refresh token 换发新 token。免认证。Handler: internal/handler/auth.go

字段	类型	必填	说明
`refreshToken`	string	是（`binding:"required"`）	refresh token

响应：200 {"success":true,"access_token":"...","refresh_token":"..."}

bash

curl -X POST $BASE/api/v1/auth/refresh -H 'Content-Type: application/json' -d '{"refreshToken":"<rt>"}'

GET /api/v1/auth/validate

用途：校验当前 token 是否有效。需登录（无空间可调用）。Handler: internal/handler/auth.go

响应：200 {"success":true,"message":"Token is valid","user":{UserInfo}}

bash

curl $BASE/api/v1/auth/validate -H "Authorization: Bearer $TOKEN"

POST /api/v1/auth/logout

用途：登出（失效当前 token）。需登录。无请求体。Handler: internal/handler/auth.go

响应：200 {"success":true,"message":"Logout successful"}

bash

curl -X POST $BASE/api/v1/auth/logout -H "Authorization: Bearer $TOKEN"

GET /api/v1/auth/me

用途：查询当前调用者身份（用户/空间/成员关系/能力）。需登录；API key 亦可（策略 apiKeyAny()，任何有效 key）。Handler: internal/handler/auth.go

响应：200 {"success":true,"data":{"user":{UserInfo},"tenant":{TenantResponse},"memberships":[...],"tenant_required":bool,"capabilities":{"can_create_tenant":bool,"auto_accept_invitation":bool}}}

bash

curl $BASE/api/v1/auth/me -H "X-API-Key: $API_KEY"

PUT /api/v1/auth/me/preferences

用途：更新个人偏好（最近活跃空间）。需登录。Handler: internal/handler/auth.go

字段	类型	必填	说明
`last_active_tenant_id`	*uint64	否	正整数设置/替换；`0` 清除（下次登录回 home）；省略则不改。`POST /auth/switch-tenant` 成功时服务端会写同一字段。

响应：200 {"success":true,"data":{UserPreferences}}

bash

curl -X PUT $BASE/api/v1/auth/me/preferences -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"last_active_tenant_id":2}'

密码策略由 GET /auth/config 提供。复杂模式允许的特殊字符集为 !@#$%^&*()_+-=[]{}|;:,.<>?；不能只根据结构体 binding 的长度标签推导完整校验规则。

POST /api/v1/auth/change-password

用途：修改密码。需登录。Handler: internal/handler/auth.go

字段	类型	必填	说明
`old_password`	string	是（`binding:"required"`）	旧密码
`new_password`	string	是（`binding:"required"`）	新密码（8–32 位，字母+数字；复杂模式另需大小写和特殊字符）

响应：200 {"success":true,"message":"Password changed successfully"}

bash

curl -X POST $BASE/api/v1/auth/change-password -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"old_password":"old","new_password":"NewPass123!"}'

修改密码必须提供正确的旧密码，新密码不能与旧密码相同。成功后撤销全部会话，需要重新登录。默认策略 8–32 位、字母和数字；复杂模式要求大小写字母、数字和特殊字符。错误详情可为 invalid_old_password、password_policy、same_password，均返回 400。

POST /api/v1/me/invitations/accept-by-token

需登录，仅操作当前用户，无空间的新用户也可调用。请求 {"token":"<invite-token>"}；有效共享邀请使当前用户加入对应空间。无效、过期、撤销的链接返回 410；空 token 返回 400。成功响应为 {success:true,data:{membership:{tenant_id,role,status,joined_at},tenant_name}}，前端据此切换空间。

bash

curl -X POST "$BASE/api/v1/me/invitations/accept-by-token" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"token":"<invite-token>"}'

我的邀请（/api/v1/me/invitations）

服务层保证“仅被邀请人可接受/拒绝”；无角色下限（无空间的新用户也可用）。Handler: internal/handler/tenant_invitation.go

GET /api/v1/me/invitations

用途：列出发给我的邀请。

查询参数	类型	必填	说明
`include_terminal`	bool	否	`true` 时包含已完结的邀请

响应：200 {"success":true,"data":{"invitations":[TenantInvitationResponse],"total":N}}

bash

curl $BASE/api/v1/me/invitations -H "Authorization: Bearer $TOKEN"

GET /api/v1/me/invitations/pending-count

用途：待处理邀请计数（轻量轮询）。

响应：200 {"success":true,"data":{"pending_count":N}}

bash

curl $BASE/api/v1/me/invitations/pending-count -H "Authorization: Bearer $TOKEN"

POST /api/v1/me/invitations/:inv_id/accept

用途：接受邀请，写入成员关系。路径参数：inv_id 邀请 ID。无请求体。

响应：200 {"success":true,"data":{"membership":{"tenant_id","role","status","joined_at"}}}

bash

curl -X POST $BASE/api/v1/me/invitations/12/accept -H "Authorization: Bearer $TOKEN"

POST /api/v1/me/invitations/:inv_id/decline

用途：拒绝邀请。路径参数：inv_id。无请求体。

响应：200 {"success":true}

bash

curl -X POST $BASE/api/v1/me/invitations/12/decline -H "Authorization: Bearer $TOKEN"

实现参考

路由注册：internal/router/router.go 的 RegisterAuthRoutes 与 RegisterMyInvitationRoutes。Handler：internal/handler/auth.go、internal/handler/auth_register_by_invite.go、internal/handler/tenant_invitation.go。

API 参考：认证与用户 ​

认证（/api/v1/auth） ​

POST /api/v1/auth/register ​

POST /api/v1/auth/register-by-invite ​

POST /api/v1/auth/invitations/lookup ​

POST /api/v1/auth/login ​

POST /api/v1/auth/auto-setup ​

GET /api/v1/auth/config ​

POST /api/v1/auth/switch-tenant ​

GET /api/v1/auth/oidc/config ​

GET /api/v1/auth/oidc/start ​

GET /api/v1/auth/oidc/url ​

GET /api/v1/auth/oidc/callback ​

POST /api/v1/auth/refresh ​

GET /api/v1/auth/validate ​

POST /api/v1/auth/logout ​

GET /api/v1/auth/me ​

PUT /api/v1/auth/me/preferences ​

POST /api/v1/auth/change-password ​

POST /api/v1/me/invitations/accept-by-token ​

我的邀请（/api/v1/me/invitations） ​

GET /api/v1/me/invitations ​

GET /api/v1/me/invitations/pending-count ​

POST /api/v1/me/invitations/:inv_id/accept ​

POST /api/v1/me/invitations/:inv_id/decline ​

实现参考 ​

API 参考：认证与用户

认证（/api/v1/auth）

POST /api/v1/auth/register

POST /api/v1/auth/register-by-invite

POST /api/v1/auth/invitations/lookup

POST /api/v1/auth/login

POST /api/v1/auth/auto-setup

GET /api/v1/auth/config

POST /api/v1/auth/switch-tenant

GET /api/v1/auth/oidc/config

GET /api/v1/auth/oidc/start

GET /api/v1/auth/oidc/url

GET /api/v1/auth/oidc/callback

POST /api/v1/auth/refresh

GET /api/v1/auth/validate

POST /api/v1/auth/logout

GET /api/v1/auth/me

PUT /api/v1/auth/me/preferences

POST /api/v1/auth/change-password

POST /api/v1/me/invitations/accept-by-token

我的邀请（/api/v1/me/invitations）

GET /api/v1/me/invitations

GET /api/v1/me/invitations/pending-count

POST /api/v1/me/invitations/:inv_id/accept

POST /api/v1/me/invitations/:inv_id/decline

实现参考