接口鉴权 (Authentication)
当您在 APayShop 中购买了类型为 dynamic_api(动态 API 额度销售)的商品时,系统会自动为您生成一个专属的 API Key。您需要使用该 Key 来调用对应的服务接口。
网页单会话策略
系统设置 disable_multi_device_login 开启后,每个用户只保留最近一次建立的浏览器 Cookie 会话。密码登录、注册、OAuth、Minimal 上游登录和 Qingpu 结账交接均使用 APay 核心的统一会话签发器。
旧网页会话在下一次访问受保护 API 时收到 HTTP 401,其中 data.code = "SESSION_REPLACED"。全局页面也会通过 GET /api/auth/session-status 取得替换通知,展示新登录的设备类型、浏览器、操作系统、UTC 登录时间、IP 和可用的地区快照。
API Token、MCP OAuth/限域令牌(apay_mcp_)、Qingpu 扩展/桌面设备 Token、管理员会话和员工委派会话使用各自独立生命周期,不会被这项仅针对网页的策略撤销。
原生应用独立会话
服务端原生登录入口调用 issueNativeSession,保留现有加密 nuxt-session Cookie 和账号 API。原生会话 90 天有效,独立核对撤销、有效期与账号状态,不更新网页单会话指针。POST /api/auth/logout 只撤销当前原生会话,旧 Cookie 重放会被拒绝。无类型标记的存量 Cookie 继续按网页会话兼容,重新登录后迁入原生会话。
浏览器应用授权使用独立的 10 分钟短期事务。主题通过 beginAppAuthorization 创建事务;密码/注册请求显式携带 X-App-Authorization,Google/GitHub 将事务绑定到独立 OAuth state。认证成功返回 {success,appAuthorization:true,returnPath,user},不建立参与互踢的网页登录。主题先用 consumeAppAuthorization 原子消费授权,再签发 App 回跳 code。待授权事务本身不是账号登录,也不会改变普通网页登录行为。
启用原生会话签发前,先执行核心增量迁移并升级所有鉴权实例。完整接入、发布与回滚说明见 docs/native-app-sessions.zh-CN.md;回归命令为 npm run check:native-sessions。
核心 MCP OAuth 2.1 与限域令牌系统
APay 内置了通用的 Model Context Protocol (MCP) OAuth 2.1 授权体系与 Streamable HTTP 服务端,允许 Claude Desktop、Cursor、Windsurf、VS Code Copilot、WorkBuddy 等 MCP 客户端以最小权限(Scoped Token)完成一键登录授权,替代全权限裸 API Key。
1. OAuth 2.1 与 RFC 9728 / RFC 8414 自动发现
- 受保护资源元数据 (RFC 9728):
GET /.well-known/oauth-protected-resource(含/.well-known/oauth-protected-resource/api/mcp子路径) - 授权服务器元数据 (RFC 8414):
GET /.well-known/oauth-authorization-server - 动态客户端注册 (RFC 7591):
POST /api/oauth/register(签发带 HMAC 签名、绑定合法redirect_uris的自包含mcp_client_...标识) - 浏览器授权同意页与接口:
- 授权确认页面:
/user/mcp-authorize - 授权预检与审批接口:
GET /api/oauth/authorize与POST /api/oauth/authorize(强制要求 PKCEcode_challenge_method=S256)
- 授权确认页面:
- 令牌兑换与刷新轮换:
POST /api/oauth/token- 支持
grant_type=authorization_code(原子级单次消费授权码 + PKCES256校验)与grant_type=refresh_token(同时轮换新 Refresh Token 与 Access Token)。
- 支持
- 令牌吊销 (RFC 7009):
POST /api/oauth/revoke
2. 限域 MCP 访问令牌 (apay_mcp_) 与 Scope Gate
- 入库 SHA-256 哈希:所有
apay_mcp_访问令牌、OAuth 授权码及 Refresh Token 在user_tokens.token中均以 SHA-256 哈希形态存储(apay_mcp_sha256_<hex>/mcp_oauth_sha256_<hex>),数据库不落明文密钥。 - 支持的权限域 (Scopes):
mcp:tools:允许访问/api/mcpJSON-RPC 2.0 端点mcp:profile:read:读取账户基础资料(/api/auth/me、/api/users/profile)mcp:orders:read:读取订单列表、支付状态与履约摘要mcp:subscriptions:read:读取当前有效订阅套餐mcp:notifications:read:读取站内通知mcp:tickets:read/mcp:tickets:write:读取或创建/回复售后工单mcp:theme:read/mcp:theme:plan:只读访问主题业务状态或生成助手执行计划(所有确认/执行写接口仍必须在网页端由人工确认)
- 高危路径硬拒绝 (Hard Deny):无论授予何种 Scope,限域令牌在
server/middleware/auth.ts均被无条件禁止访问/api/admin/**、/api/users/tokens、/api/users/password、/api/users/email、/api/users/account-deletion、/api/users/billing、/api/users/wallet、/api/orders/checkout、/api/orders/topup、/api/payments/**、/api/qingpu/stores及/api/qingpu/device-tokens。 - 手动签发与管理:用户也可在
/user/tokens页面手动创建、查看与吊销带 Scope 的apay_mcp_令牌(GET/POST /api/users/tokens、DELETE /api/users/tokens/:id),页面内置 Claude Desktop / Cursor / Windsurf 的mcpServersJSON 配置一键复制。 - 管理员紧急吊销:管理员可通过
POST /api/admin/users/:id/revoke-tokens一键吊销指定用户名下的全部 API / MCP 令牌并清除关联 Refresh Token。
3. 核心 MCP 服务端点 (/api/mcp)
- 端点地址:
POST /api/mcp(Streamable HTTP JSON-RPC 2.0) - 鉴权要求:强制要求
Authorization: Bearer <token>或X-Api-Key: <token>。仅携带浏览器 Cookie 的请求会被拒绝并返回401与WWW-Authenticate: Bearer resource_metadata="..."响应头,从而消除跨站页面通过 Cookie 对 MCP 工具执行端点的 CSRF 攻击面。 - 内置核心工具:
apay_get_profile/apay_get_account_profile(mcp:profile:read)apay_list_products(mcp:tools)apay_list_orders/apay_get_order_detail(mcp:orders:read)apay_list_subscriptions(mcp:subscriptions:read)apay_list_notifications(mcp:notifications:read)apay_list_tickets/apay_get_ticket_detail(mcp:tickets:read)apay_create_ticket/apay_reply_ticket(mcp:tickets:write)- 主题模块可通过
server/utils/mcpServer.ts的registerMcpTool()注册扩展工具。
账户注销申请与永久封存机制
APay 核心内置了完整的「用户提交申请 -> 后台管理员审核 -> 永久封存禁登」账户生命周期能力(account_deletion_requests 表 + users.status = -1),在不破坏订单、充值与审计外键完整性的前提下永久终止账户登录权限。
- 用户侧接口(仅允许主账号网页登录会话调用,禁止 API/MCP 令牌与员工委派会话调用):
GET /api/users/account-deletion:获取当前账户状态、密码/第三方验证模式、资产预检指标(可用余额、生效中订阅数、历史已付订单数)、待审申请及历史记录。POST /api/users/account-deletion:核验当前登录密码(纯第三方登录账号核验完整绑定邮箱confirmEmail)后提交待审核注销申请,自动留存申请时刻的资产与环境快照。POST /api/users/account-deletion/cancel:在管理员审核前撤回处于pending状态的注销申请。- 核心页面与可复用组件:
/user/account(<AccountDeletionPanel />与useAccountDeletion())。
- 管理后台审核与直接封存接口(受
customers:view/customers:edit权限保护并写入操作审计日志):GET /api/admin/users/deletion-requests:分页查询注销申请记录,支持按状态与关键词筛选并返回全局各状态汇总计数。POST /api/admin/users/deletion-requests/:id/review:审核待处理申请,支持批准封存(action = "approve")或驳回(action = "reject",自动向用户下发站内通知说明原因)。DELETE /api/admin/users/:id:管理员直接对指定客户执行无外键冲突的封存删除。
- 永久封存与全链路禁登(
users.status = -1):- 审核通过或直接封存后,
users.status置为-1、清空currentSessionId、吊销全部活跃user_sessions(网页、原生客户端、App 授权事务)、清除一次性与 OAuth 刷新令牌、吊销全部个人 API/MCP/设备令牌、将生效中订阅标记为期末不续订(cancelAtPeriodEnd = true),并广播user.deleted事件。 - 封存账户在全局鉴权中间件、原生会话校验、Bearer 令牌、密码登录、第三方 OAuth 登录与绑定、找回密码、
find-or-create及同邮箱重新注册入口均会被拦截并返回ACCOUNT_ARCHIVED。
- 审核通过或直接封存后,
鉴权方式
APayShop 采用标准的 HTTP Authorization 头部进行鉴权。在发送 API 请求时,请将您的 API Key 作为 Bearer Token 放入请求头中。
格式要求
请求头名称: Authorization
请求头内容: Bearer 您的_API_KEY
示例请求
以下是一个使用 cURL 发送带鉴权请求的示例:
curl -X GET https://yourdomain.com/api/v1/some-service \
-H "Authorization: Bearer sk_test_1234567890abcdef" \
-H "Content-Type: application/json"
如何获取 API Key?
- 在前台商店购买
dynamic_api类型的商品并完成支付。 - 支付成功后,前往 "Order History" (订单历史) 页面。
- 点击对应订单的详情,您将直接在履约结果(Fulfillment Result)区域看到系统为您分配的 API Key 以及可用额度。
⚠️ 安全警告
请将您的 API Key 视为密码一样妥善保管。绝对不要将其硬编码在客户端代码(如浏览器端 JS、移动端 App)中,也不要提交到公开的 GitHub 仓库。如果您的密钥泄露,请立即联系管理员在后台将其作废并重新生成。
额度消耗机制
每次使用有效的 API Key 成功调用计费接口时,系统会自动从您的可用额度(Quota)中扣除相应的值。
当额度耗尽后,API 将拒绝服务并返回 402 Payment Required 或 403 Forbidden 状态码。您可以再次购买该商品来补充额度。