API 参考
NanakoHome 的应用 API 位于 /api/v1，OAuth 提供方接口另位于 /oauth。本页示例使用面向公网的配置地址 https://api.nanako.org/api/v1；调用其他部署时请替换 origin。未设置 VITE_API_URL 时，已核验前端源码会回退到 http://localhost:8080/api/v1。
本页已于 2026-09-10 对照 frontend/src/services/api.ts 和 backend/internal/api/router.go 核验路由前缀与客户端行为。公网地址只是配置目标，不证明部署当前在线。Nanako 尚无纳入仓库的 OpenAPI 契约，因此请求和响应类型可能随应用演进。
浏览器会话鉴权
受保护的 /api/v1 请求携带短期 access token：
Authorization: Bearer <access_token>
NanakoHome 浏览器客户端把 token 保存在内存和当前标签页的 sessionStorage 中。请求会携带凭据，让服务端通过 HttpOnly cookie 轮换 refresh token。受保护请求返回 401 时，客户端会合并并发刷新，只尝试一次 POST /api/v1/auth/refresh，成功后重放原请求。
不要在应用 JavaScript 中持久化 NanakoHome 的会话 refresh token。该浏览器会话机制与批准的第三方客户端取得的 OAuth access/refresh token 相互独立。
大多数 JSON 错误包含 error 字段。上传接口使用 multipart form data，OAuth token 接口使用表单编码，任务和通知事件流使用 text/event-stream。
如果你要做的是第三方接入 —— 让用户用 Nanako 账号登录你自己的产品 —— 那是另一套机制, 有独立的参考文档:见 OAuth 2.0。
公开应用路由
下列路由无需 Nanako 浏览器会话。认证、验证码和取件接口受限流约束，也可能依赖部署配置。
| 方法与路由 | 用途 |
|---|---|
GET /health | 进程健康响应 |
GET /api/v1/auth/methods | 获取已配置的登录方式和可选 Geetest ID |
GET /api/v1/auth/pubkey | 浏览器密码加密辅助逻辑使用的公钥 |
POST /api/v1/auth/check | 检查手机/邮箱账户是否存在及是否有密码 |
POST /api/v1/auth/sms/send | 请求短信验证码 |
POST /api/v1/auth/email/send | 请求邮件验证码 |
POST /api/v1/auth/register/phone | 用手机验证码和密码注册 |
POST /api/v1/auth/register/email | 用邮件验证码和密码注册 |
POST /api/v1/auth/login/phone | 手机密码登录 |
POST /api/v1/auth/login/email | 邮箱密码登录 |
POST /api/v1/auth/sms/login | 手机验证码登录 |
POST /api/v1/auth/email/login | 邮件验证码登录 |
POST /api/v1/auth/password/reset/phone | 用手机验证码重置密码 |
POST /api/v1/auth/password/reset/email | 用邮件验证码重置密码 |
GET /api/v1/auth/{google,github,apple}/url | 启动一个已配置的外部身份登录流程 |
GET /api/v1/auth/{google,github}/callback | Google 或 GitHub 回调 |
POST /api/v1/auth/apple/callback | Apple form-post 回调 |
POST /api/v1/auth/exchange | 用前端一次性回调码换取浏览器会话 |
POST /api/v1/auth/refresh | 轮换 HttpOnly refresh cookie 并签发 access token |
POST /api/v1/auth/2fa/verify | 用 TOTP 或恢复码完成登录 |
GET /api/v1/config/features | 公开的应用可见性/维护状态映射 |
GET /api/v1/todo/public/:uuid | 读取共享的公开待办看板 |
GET /api/v1/showcase/apps | 读取公开应用橱窗 |
POST /api/v1/honeycomb/pickup | 兑换蜂巢取件码 |
GET /api/v1/honeycomb/download/:token | 下载已兑换的蜂巢文件 |
GET /s/:slug | 获取公开托管脚本 |
认证响应也可能返回 {requires_2fa: true, pending_token: "..."}。此时尚未签发 access token，必须先完成 /api/v1/auth/2fa/verify。
受功能开关控制的应用路由可能返回 HTTP 503 和 error: "feature_disabled"。客户端应显示维护状态，不能仅凭首页卡片推断功能可用。
受保护路由组
当前浏览器客户端使用以下已鉴权路由组。此表是实现清单，不代表每条路由都承诺供第三方直接调用。
| 前缀 | 已核验路由中的操作 |
|---|---|
/api/v1/user | 当前资料、初始设置、资料更新、外部身份、登录会话和 TOTP；账户注销路由虽已注册，但受下述 UUID/整数缺陷阻断 |
/api/v1/auth | 登出、外部身份绑定地址 |
/api/v1/user/password | 设置或修改密码（POST /set、POST /change） |
/api/v1/preferences | 收藏、最近使用和单应用设置 |
/api/v1/pomodoro | 记录专注会话和读取统计 |
/api/v1/todo | 看板、事项、共享和用户搜索 |
/api/v1/honeycomb | 存入和管理文件 |
/api/v1/scripts | 创建、列出、读取、修改和删除托管脚本 |
/api/v1/translate | 上传、列出、查看、订阅、取消和下载翻译任务；列出提供方 |
/api/v1/mineru | 上传、列出、查看、订阅、取消和下载解析任务 |
/api/v1/images | 上传、列出和删除图片 |
/api/v1/ghspeed | 管理下载 key，查看用量、日志和边缘节点信息 |
/api/v1/oauth | 开发者申请、客户端、用户授权和授权日志管理 |
/api/v1/apps/uptime/launch | 创建跳入外部 NanoUptime 应用的一次性 SSO 地址 |
/api/v1/notifications | 收件箱、未读数、SSE、已读/归档、偏好和按客户端静音 |
/api/v1/admin | 仅管理员可用的用户、邮件、功能、翻译、橱窗和 OAuth 管理 |
浏览器 Web Push 与 APNs 当前不是路由中的可用 API。通知偏好矩阵预留了这些渠道名，但已核验实现中没有设备订阅注册路由。
DELETE /api/v1/user/account 已注册，但已核验 handler 把认证得到的 UUID 用户 ID 断言成 uint。正常的已认证请求会在删除事务之前失败。修正并测试 handler 前，不要把该路由作为可用操作提供。
OAuth 2.0 / OpenID Connect 提供方
审核通过的开发者可以在 Nanako 开发者中心创建客户端。必须逐项登记精确的重定向 URI；未登记的地址会被授权端点拒绝。当前实现支持授权码流程、使用 client_secret 的机密客户端，以及使用 plain 或 S256 的 PKCE。
| 方法与路由 | 用途 |
|---|---|
GET /oauth/authorize | 校验授权请求并把浏览器送到 Nanako 授权确认界面 |
POST /oauth/token | 交换授权码或轮换 OAuth refresh token |
GET /oauth/userinfo | 按已授权 scope 返回用户信息 |
POST /oauth/revoke | 撤销 access/refresh token；机密客户端必须鉴权 |
GET /.well-known/openid-configuration | 提供方发现元数据 |
授权参数包括 client_id、redirect_uri、response_type=code、scope、可选 state、可选 code_challenge 与 code_challenge_method，以及可选 prompt=none。实现支持以下 scope：
| Scope | 返回的用户信息 |
|---|---|
openid | 稳定的 sub 标识 |
profile | name 和 picture |
email | 存在时返回 email 和 email_verified |
phone | 存在时返回 phone_number 和 phone_number_verified |
Token 端点接收 application/x-www-form-urlencoded。交换授权码时，提交 grant_type=authorization_code、授权码、client_id、完全一致的 redirect_uri，再根据签发方式提供匹配的 PKCE code_verifier 或机密客户端的 client_secret。当前实现签发两小时有效的 bearer access token，并在每次使用时轮换 OAuth refresh token。
已核验路由把 token、user-info 和撤销 handler 挂载在 /oauth/*，但当前发现 handler 生成的是 /api/v1/oauth/* 地址。依赖自动发现前请核验目标部署。本页采用 backend/internal/api/router.go 实际挂载的路径。
当前 token 响应没有 id_token，但发现元数据宣告了 RS256 ID-token 签名。因此，有 discovery 和 user-info 接口并不代表完整的 OpenID Connect ID-token 流程已经实现。
PKCE 只允许授权码兑换阶段不提交 client secret；refresh-token 与撤销 handler 仍无条件要求 client_secret。纯浏览器公共客户端不能仅凭 PKCE 通过这些 handler 续期或撤销 token。
不要把机密客户端的 secret 放进浏览器代码。开发者中心只会在客户端创建或重新生成时显示一次 secret；请把它存放在应用的服务端组件中。