API 参考

基础地址:https://api.rempar.org/v1。全部使用 JSON。成功的响应包裹在 {"data": ...} 中,错误包裹在 {"error": {"code": "...", "message": "..."}} 中。使用每台设备专属的 Bearer 令牌进行身份验证。

该 API 是零知识的:它从不接收密码或明文内容。欢迎第三方客户端接入,只要遵守 v1 协议即可。

健康检查

GET /v1/health
→ { "data": { "status": "ok", "release": "1.1.0" } }

身份验证

方法 路由 请求体 响应
POST /auth/prelogin {email} {kdf, kdf_salt}。如果电子邮件地址未知,则返回确定性的虚假盐值。
POST /auth/register {email, auth_key, kdf, kdf_salt, device} 201 {status: "verification_sent"}。系统会通过电子邮件发送一个六位数验证码。
POST /auth/verify-email {email, code} {}
POST /auth/login {email, auth_key, device, totp?, code?} {tokens, device_id, vault_key_sealed?}。如果已启用双重验证但未提供验证码,返回错误 totp_required(403)。随后返回 email_code_required(403):系统通过电子邮件发送一个六位数验证码,将其放在 code 中再次提交即可获得令牌(10 分钟,最多 5 次尝试)。
POST /auth/refresh {refresh_token} {access_token, refresh_token, ...}。轮换使用;重放会导致设备被撤销。
POST /auth/logout 撤销当前设备。
POST /auth/recover {email, recovery_auth, totp?} 恢复套件证明:返回 {vault_key_recovery, recovery_token}(15 分钟)。如果已启用双重验证,返回 totp_required。
POST /auth/recover/complete {email, recovery_token, auth_key, kdf, kdf_salt, vault_key_sealed, device} 设置新的主密码:替换身份验证密钥和重新密封的保险库密钥,撤销所有其他设备,并登录当前设备({tokens, device_id, vault_key_sealed})。

device:{name, platform, client_id},其中 client_id 是由客户端选择的 UUID,对该设备保持不变。

kdf:{"algo": "argon2id", "m": 65536, "t": 3, "p": 4}。客户端会拒绝弱于 m=19456、t=2、p=1 的参数。

账户

方法 路由 说明
GET /account 电子邮件地址、双重验证状态、保险库修订号、订阅 {plan, active, until}。
GET /account/subscription 仅返回订阅信息。
POST /account/password 更改主密码后替换 auth_key。客户端需先重新发布重新密封的保险库密钥。
GET /account/devices 活动设备。
DELETE /account/devices/{id} 撤销一台设备。
POST /account/totp/setup 生成一个密钥并返回 {secret, otpauth_url}。
POST /account/totp/enable {code}:启用双重验证。
POST /account/totp/disable {code}:停用双重验证。

保险库

方法 路由 说明
PUT /vault/key {vault_key_sealed, vault_key_recovery?}:仅限密封的数据块,以原子方式替换。始终允许(用于恢复)。
GET /vault/items?since=<revision>&limit=500 {items: [{id, revision, deleted, blob, updated_at}], revision}。需要有效的订阅。
POST /vault/items {base_revision, items: [{id, blob|null}]} → {revision, conflicts: []}。blob: null 表示删除(墓碑记录)。如果 base_revision 已过时,服务器会返回 newer_items,而不执行写入。每次最多提交 500 个条目。需要有效的订阅。

订阅

Cloud 订阅以 7 天免费试用(trial)开始,通过 Stripe、App Store 或 Google Play 开通(参见 GET /v1/account/subscription)。没有有效订阅时,同步路由会返回 402 subscription_required;密封的保险库密钥仍可读取,以便进行恢复。客户端显示“等待中”,并继续在本地运行。

错误代码

代码 HTTP 含义
invalid_credentials 401 电子邮件地址、密钥或验证码错误。
unauthenticated 401 令牌缺失、已过期,或设备已被撤销。
email_unverified 403 尚未输入电子邮件验证码。
totp_required 403 需提供 totp。
subscription_required 402 Cloud 订阅已到期。
email_taken 409 该电子邮件地址已有经过验证的账户。
stale_revision 409 请先拉取返回的 newer_items。
token_reused 401 检测到重放,设备已被撤销。

速率限制

预登录 30 次/分钟,注册和验证 10 次/分钟,登录 15 次/分钟,刷新 30 次/分钟,需身份验证的路由每台设备 240 次/分钟。

示例

curl -s https://api.rempar.org/v1/auth/prelogin \
  -H 'Content-Type: application/json' \
  -d '{"email":"vous@example.org"}'

这里没有找到答案? support@rempar.org