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