后端 API 概览

Inklet 后端提供 RESTful JSON API，用于认证、设备管理和计费。后端使用 Go 和 Chi 路由器构建。

基础 URL

环境	URL
生产环境	https://auth.iminklet.com
本地开发	http://localhost:4000

响应格式

所有响应返回 JSON 并附带相应的 HTTP 状态码。成功响应使用 200 或 201；错误响应返回包含 message 字段的 JSON 内容：

{
  "message": "description of the error"
}

认证

受保护的接口需要在 Authorization 请求头中提供有效的 JWT 访问令牌：

Authorization: Bearer {accessToken}

访问令牌有效期较短。使用刷新接口可以在无需重新认证的情况下获取新令牌。

令牌生命周期

访问令牌在较短的时间窗口后过期（通常为 15 分钟）。刷新令牌有效期较长，但每次使用后会进行轮换 --- 当签发新的令牌对时，旧的刷新令牌将被废止。

API 分组

API 分为三组：

认证（/auth/*）

用户注册、登录、OAuth（Google 和 Apple）、会话管理、个人资料更新以及订阅计费。

参见：认证 | 计费

设备（/api/devices/*）

设备列表、绑定（NFC 和配对码）、解绑、命令下发和状态查询。

参见：设备

健康检查（/health）

一个简单的健康检查接口，供负载均衡器和监控系统使用。

curl https://auth.iminklet.com/health

{
  "status": "ok"
}

常见 HTTP 状态码

状态码	含义
200	成功
201	资源已创建
400	请求无效 --- 字段缺失或格式错误
401	未授权 --- 令牌缺失或已过期
403	禁止访问 --- 你不是该资源的所有者
404	资源未找到
409	冲突 --- 邮箱、用户名重复或设备已被绑定
410	已失效 --- 资源已被删除或过期
500	服务器内部错误

频率限制

生产环境中的 API 请求可能受到频率限制。如果超出限制，你将收到 429 Too Many Requests 响应。请等待 Retry-After 响应头指定的时间后重试。

CORS

生产环境后端允许来自 https://portal.iminklet.com 的跨域请求。本地开发允许 http://localhost:5173。