API 参考

#基础约定

使用 Swift SDK 时无需直接调用这些端点。本页面向需要自行实现协议或排查问题的开发者。

#认证方式

#签名

除换 token 外，所有第三方数据调用都必须同时携带 access token 与该授权审批私钥的签名。public client 的撤销请求也需要签名。

规范串（UTF-8，各段以 \n 连接，末尾无换行）：

{METHOD}\n{PATH}\n{TIMESTAMP}\n{NONCE}\n{SHA256_HEX(BODY)}

• METHOD：大写的 HTTP 方法。
• PATH：不含查询串的路径，例如 /api/oauth/requests/3f6b…/patch。
• BODY：实际发送的请求体字节。签名后不得再改动请求体（包括重新序列化）。无请求体时取空串，其 SHA-256 为 e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855。
• 时间戳与服务器时间相差不得超过 ±300 秒。
• nonce 在同一授权内 10 分钟内只能使用一次；即使签名校验失败，已提交的 nonce 也视为已使用。

GET /api/oauth/account HTTP/1.1
Host: password.tminos.com
Authorization: Bearer 3q2-7wEXAMPLEACCESSTOKEN
x-pm-timestamp: 1761177600
x-pm-nonce: n-0123456789abcdef
x-pm-signature: KngAgL1nChfn4NugEnlNlesKA8EtmrhpsL1GU9pU_Z0AcwkQRzP9iasdaFfe3nEVcvCGUT92eWHzzZCEX849DQ

上例签名可用测试向量中的公开测试密钥复现。

签名失败的错误码：signature_required（缺请求头）、signature_invalid（格式或签名不对）、timestamp_out_of_window、nonce_replayed。

#登记 client

#POST /api/oauth/clients

登记一个接入应用。认证：账号会话。MimiKey for Mac 的「开发者接入」页面调用的就是这个端点。

POST /api/oauth/clients HTTP/1.1
Authorization: Bearer <会话令牌>
Content-Type: application/json

{
  "name": "我的 AI 助手",
  "description": "帮我登录网站完成对账",
  "client_type": "public",
  "platforms": ["ios", "macos"],
  "redirect_uris": ["com.example.ai://mimikey/callback"],
  "brand": { "color": "#1d4ed8", "logo_url": "https://cdn.example.com/logo.png", "homepage": "https://example.com" }
}

{
  "client_id": "pmc_Xk3vQ9pL2mN8rT4w",
  "client_type": "public",
  "name": "我的 AI 助手",
  "platforms": ["ios", "macos"],
  "brand": { "color": "#1D4ED8", "logo_url": "https://cdn.example.com/logo.png", "homepage": "https://example.com" }
}

confidential client 的响应另含 client_secret，只返回这一次；服务器只保存其哈希。

错误：invalid_input、invalid_client_type、invalid_redirect_uris、invalid_public_key、invalid_platforms、invalid_brand、mode_retired。

#GET /api/oauth/clients

列出当前账号登记的 client。认证：账号会话。

{
  "clients": [
    {
      "client_id": "pmc_Xk3vQ9pL2mN8rT4w",
      "name": "我的 AI 助手",
      "description": "帮我登录网站完成对账",
      "client_type": "public",
      "redirect_uris": ["com.example.ai://mimikey/callback"],
      "platforms": ["ios", "macos"],
      "brand": { "color": "#1D4ED8" },
      "has_seal_key": false,
      "has_service_key": false,
      "disabled": false,
      "platform_disabled": false,
      "active_grants": 3,
      "created_at": "2026-10-23T08:00:00Z"
    }
  ]
}

disabled 表示开发者已停用，platform_disabled 表示被平台运营方停用。

#DELETE /api/oauth/clients/{id}

停用一个 client。认证：账号会话。该 client 的全部授权立即撤销、令牌失效、未完成请求过期，不可恢复。响应 { "ok": true }；不存在或已停用时返回 404 client_not_found。

#授权（MimiKey App 侧）

以下端点由 MimiKey App 用用户的账号会话调用，接入方不需要实现，列出供理解协议。

#深链

SDK 打开以下深链启动 MimiKey：

回调参数见回调状态汇总。

#GET /api/oauth/authorize/info

同意卡所需的数据。查询参数：client_id。

{
  "client": {
    "id": "pmc_Xk3vQ9pL2mN8rT4w",
    "name": "我的 AI 助手",
    "description": "帮我登录网站完成对账",
    "client_type": "public",
    "brand": { "color": "#1D4ED8", "logo_url": "https://cdn.example.com/logo.png", "homepage": "https://example.com" },
    "platforms": ["ios", "macos"]
  },
  "vaults": [
    { "vault_id": "8d4c…", "name": null, "kind": "personal", "default": true },
    { "vault_id": "b2a1…", "name": "家庭", "kind": "shared", "default": false }
  ]
}

只返回该用户拥有的库。为兼容 v2，client 中还包含 client_id、seal_public_key、service_public_key。错误：404 client_not_found、403 client_disabled。

#POST /api/oauth/authorize

记录用户的同意并签发授权码。

响应：{ "code": "…", "state": "…" }。授权码 10 分钟有效、只能使用一次。

#令牌

#POST /api/oauth/token

不需要会话。public client 不得携带 client_secret（携带时返回 400 invalid_client）。

授权码换令牌：

POST /api/oauth/token HTTP/1.1
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": "q8V0…",
  "client_id": "pmc_Xk3vQ9pL2mN8rT4w",
  "redirect_uri": "com.example.ai://mimikey/callback",
  "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
}

{
  "access_token": "3q2-7wEXAMPLEACCESSTOKEN",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "Zp9-EXAMPLEREFRESHTOKEN",
  "refresh_expires_in": 2592000,
  "grant_id": "6f1d2c3b-4a59-4e68-8b7c-9d0e1f2a3b4c",
  "account_id": "0b7e…",
  "vaults": [{ "vault_id": "8d4c…", "mode": 1 }],
  "client_type": "public",
  "account_identity_public_key": "9Xwg4YSHxLN9dr2JSRYL_wfRh_0iafGiNzQtT5blNys"
}

注意 授权码在第一次兑换尝试时即被消耗。PKCE 校验失败（invalid_grant）、回调地址不符等错误之后，同一授权码不能再用，需要重新授权。

续期：

续期响应与上例相同，但不含 vaults（授权范围不会因续期改变）。

• 轮换： 每次续期都会作废所用的 refresh token 并签发新的；新 refresh token 自本次续期起 30 天有效。
• 复用检测： 已作废的 refresh token 再次出现时返回 401 refresh_token_reused，并立即吊销该授权的全部令牌。收到后必须停止自动重试，引导用户重新授权。
• 续期不需要签名；但续期得到的 access token 仍只能配合审批钥签名使用。

#撤销

#POST /api/oauth/revoke

撤销某个令牌所属的授权。幂等：未知令牌也返回 { "ok": true }。

撤销后，该授权的 access token 与 refresh token 立即失效，未完成的请求全部置为 expired。

#账号

#GET /api/oauth/account

签名调用。返回授权用户的账号身份公钥与本授权的库。

{
  "account_id": "0b7e…",
  "identity_public_key": "9Xwg4YSHxLN9dr2JSRYL_wfRh_0iafGiNzQtT5blNys",
  "vaults": [
    { "vault_id": "8d4c…", "name": null, "kind": "personal", "mode": 1 }
  ]
}

identity_public_key 在账号尚未生成身份密钥时可能为 null，此时无法发起 update_item。

#请求

#请求对象

POST /api/oauth/requests、PUT …/patch 与 GET /api/oauth/requests/{id} 返回同一种对象（创建时只含部分字段）：

#状态与等待

选条目、新建与修改请求没有 approved 中间状态：卡上的操作本身就是批准。服务器在读取时惰性判定过期：超过 expires_at 的未结束请求会显示为 expired。

#POST /api/oauth/requests

签名调用。创建一个请求。

每个授权最多同时有 100 个未结束的请求（含草稿），超过时返回 429 too_many_requests。

#pick_item

{ "op": "pick_item", "vault_id": null, "hint": { "url": "https://bank.example.com", "kind": "login" }, "reason": "登录示例银行完成对账" }

{ "request_id": "a1b2c3d4-…", "state": "pending", "waiting_on": "user", "waiting_reason": "pick", "expires_at": "2026-10-23T08:40:00Z", "state_changed_at": "2026-10-23T08:30:00Z" }

有效期 10 分钟。在 trust 策略下也需要用户选择。

#get_item

有效期 10 分钟。ask 策略下初始为 pending，trust 策略下初始为 approved。

#create_item

{ "op": "create_item", "vault_id": "8d4c…", "kind": "login", "prefill": { "title": "示例银行", "url": "https://bank.example.com/login", "username_hint": "me@example.com" }, "reason": "登录示例银行完成对账" }

有效期 30 分钟，初始恒为 pending。同一授权、同一个库中已有网址主机名相同的待处理新建请求时，返回该请求并带 "existing": true。

#update_item

创建时不得携带 patch_enc。请求以 draft 状态创建（有效期 60 秒，不出现在用户设备上），随后用 PUT …/patch 上传补丁。

{ "op": "update_item", "vault_id": "8d4c…", "item_id": "3f6b8f7e-…", "fields": ["password"], "reason": "已在网站上更换密码，同步到 MimiKey" }

{ "request_id": "a1b2c3d4-…", "state": "draft", "waiting_on": "client", "waiting_reason": "patch", "expires_at": "2026-10-23T08:31:00Z", "state_changed_at": "2026-10-23T08:30:00Z" }

#list_items

结果只含元数据（不含密码与备注）。Swift SDK 不提供此操作。

#上传修改补丁

#PUT /api/oauth/requests/{id}/patch

签名调用。为 draft 状态的 update_item 请求上传密封补丁，请求随即变为 pending，有效期重置为 30 分钟。

补丁的构造：

• 收件人：account_identity_public_key（或 GET /api/oauth/account 的 identity_public_key）
• AAD：password-manager/oauth-patch/v1/{grant_id}/{request_id}
• 明文：{"patch":{"password":"新值"}}，只能包含 fields 中声明的字段

{ "patch_enc": "{\"format\":1,\"epk\":\"PHld72bS…\",\"envelope\":{\"format\":2,\"nonce\":\"8Ovm4dzX…\",\"ciphertext\":\"9eSfVW9L…\"}}" }

响应为请求对象，state 为 pending、waiting_reason 为 review。错误：invalid_patch（格式不对或过大）、request_not_found、409 request_not_draft（不是草稿、已过期或不是 update_item）。

#GET /api/oauth/requests/{id}

签名调用。查询请求；完成后携带结果。建议每 2 秒轮询一次，并在 App 回到前台时立即查询。

{
  "request_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "state": "completed",
  "op": "pick_item",
  "vault_id": null,
  "item_id": null,
  "created_at": "2026-10-23T08:30:00Z",
  "expires_at": "2026-10-23T08:40:00Z",
  "state_changed_at": "2026-10-23T08:31:12Z",
  "waiting_on": null,
  "waiting_reason": null,
  "result_enc": "{\"format\":1,\"epk\":\"FiF4WQXs…\",\"envelope\":{…}}",
  "picked_item": { "id": "3f6b8f7e-…", "title": "示例银行", "url": "https://bank.example.com/login", "kind": "login" }
}

用 seal 私钥、AAD password-manager/oauth-result/v1/{grant_id}/{request_id} 打开 result_enc：

{
  "item": {
    "id": "3f6b8f7e-9c1d-4e2a-8b3c-4d5e6f7a8b9c",
    "revision": 4,
    "record": {
      "title": "示例银行",
      "username": "me@example.com",
      "password": "correct horse battery staple",
      "url": "https://bank.example.com/login",
      "notes": "",
      "kind": "login",
      "extra": {},
      "updated_at": "2026-10-23T08:00:00.000Z"
    }
  }
}

list_items 的结果为 { "v": 2, "items": [{ "id", "meta": { "title", "username", "url", "kind", "updated_at" } }] }。

#POST /api/oauth/requests/{id}/cancel

签名调用，无请求体。取消一个未结束的请求（draft、pending 或 approved）。响应：{ "request_id": "…", "state": "cancelled" }。已结束的请求返回 409 request_not_pending。

#旧模式 2 端点

以下端点仅为既有的模式 2 授权保留只读兼容，新授权无法使用：

#设备端端点

以下端点由 MimiKey App 用用户的账号会话调用，接入方不会用到：

#用户授权管理

#运营端：停用接入方

仅平台运营方可用，认证为独立的管理员会话（与用户会话隔离）。

停用的效果：

• 该 client 的全部授权撤销，全部令牌失效，未完成的请求全部置为 expired；
• 之后的签名调用返回 401 client_disabled；
• authorize/info 与 authorize 返回 403 client_disabled，MimiKey App 拒绝该 client 的深链；
• 操作写入管理审计日志。

enable 只解除停用标记，不会恢复已撤销的授权；用户需要重新授权。