开发者概览
用 MimiKey 第三方授权 v3（SDK 批准卡）让你的 App 在用户逐次批准下读取、新建和修改凭据，而不接触任何未授权的明文。
它能做什么
MimiKey 第三方授权让你的 App（例如 AI 助手、自动化工具、企业内部应用）在完成任务时向用户的 MimiKey 请求凭据。用户不离开你的 App，在 MimiKey 自己渲染的批准卡上决定给不给、给哪条、填什么、改什么；你的 App 拿到的永远是用户批准后、密封给这一次授权的单条结果。
| 你可以 | 你不能 |
|---|---|
| 请用户从授权的库里选一条条目，拿到完整记录 | 列出或浏览用户的条目 |
| 读取一条已知 ID 的条目（按用户的审批策略） | 在没有用户批准的情况下读取任何内容 |
| 请用户在 MimiKey 里新建一条条目并拿回结果 | 自己绘制凭据输入界面或经手用户输入的密码 |
| 提交一次修改，由用户在差异卡上确认后写入 | 绕过用户直接写入 |
| 随时撤销自己的授权 | 获得库钥或任何长期解密能力 |
核心概念
| 概念 | 说明 |
|---|---|
| client（接入应用） | 你登记的应用，标识为 client_id（pmc_ 前缀）。分两类：public（App 内 SDK，无 secret，用 PKCE 换 token）与 confidential（你的服务端持有 client_secret）。iOS / macOS App 一律使用 public。 |
| grant（授权） | 某个用户对某个 client 的一次同意。每个 grant 绑定一把审批钥（Ed25519，签名每次调用）和一把 seal 公钥（X25519，接收密封结果），并限定到用户勾选的若干库。 |
| request（请求） | 你发起的一次操作：pick_item、get_item、create_item、update_item。每个请求都有状态机与有效期。 |
| 批准卡 | MimiKey App 为一次授权或一个请求渲染的界面：同意卡、选条目卡、读取批准卡、安全卡（新建）、修改卡。详见批准卡。 |
| 执行设备 | 渲染批准卡的那台已解锁的 MimiKey 设备。卡上的批准即执行：在本机解密或写入、密封结果、上传、跳回你的 App。 |
| 审批策略 | 用户在同意时选择：ask（每次读取都询问）或 trust（读取不再逐次询问，但仍需打开 MimiKey 执行）。新建、选条目和修改永远需要用户在卡上操作。 |
为什么批准卡运行在 MimiKey 里
任何让用户做决定的界面，如果运行在你的 App 进程里，你的进程就能替用户点按钮、在上面盖一张假卡，或直接读取用户输入的内容——无论你是否有此意图，用户和 MimiKey 都无法验证。因此 v3 规定：
- 同意、选条目、读取、新建、修改的界面一律由 MimiKey 自己的进程渲染（iOS App 与 Mac App）。
- 你的 App 里只允许出现无决策的前置提示，例如「即将打开 MimiKey」，以及等待界面上的「重试」「取消」。
- 你可以定制的只有品牌白名单：名称、图标、品牌色、主页。卡的结构、按钮语义和风险提示由 MimiKey 固定。
这也是你的 App 能被用户信任的前提：用户知道自己看到的每一张卡都是真的。
端到端流程
你的 App（SDK） MimiKey 服务器 MimiKey App（用户设备）
│ │ │
1. ├─ 生成 seal 钥、审批钥、PKCE、state
2. ├─ 打开 mimikey://authorize ───────────────────────────────▶│ 同意卡
3. │ │◀──── POST /api/oauth/authorize ┤ 用户点「允许」
4. │◀──────────────────── 回调 <redirect>?mk=authorize&code&state
5. ├─ POST /api/oauth/token（code + code_verifier）▶│
│◀──────── access_token、refresh_token、grant_id ┤
6. ├─ POST /api/oauth/requests（签名）─────────────▶│
│◀────────────────────────────── request_id ─────┤
7. ├─ 打开 mimikey://request?id=… ────────────────────────────▶│ 批准卡
8. │ │◀── 设备执行、密封、上传结果 ───┤ 用户批准
9. │◀────────────────── 回调 <redirect>?mk=request&request_id&state&status
10. ├─ GET /api/oauth/requests/{id}（签名，同时每 2 秒轮询兜底）▶│
│◀────────────────────────── result_enc ─────────┤
11. └─ 用 seal 私钥在本机解开结果
- SDK 在本机生成本次授权专属的 seal 密钥对与审批密钥对（存系统钥匙串），以及 PKCE verifier 与随机
state。 - SDK 打开
mimikey://authorize深链，带上client_id、回调地址、state、PKCE challenge 以及两把公钥。 - MimiKey 校验 client 与回调地址，在用户解锁后显示同意卡；用户勾选库、选择审批策略并点「允许」。
- MimiKey 打开你的回调地址，只带
code与state。 - SDK 用
code和 PKCE verifier 换取 access token（1 小时）与 refresh token（30 天滑动有效）。 - 需要凭据时，SDK 以 token + 审批钥签名创建一个 request。
- SDK 打开
mimikey://request深链，MimiKey 显示对应的批准卡。 - 用户批准后，执行设备在本机完成解密或写入，把结果密封给 seal 公钥后上传。
- MimiKey 打开回调地址，只带
request_id、state与status。 - SDK 取回请求；即使回调丢失（用户手动切回），每 2 秒一次的轮询与回到前台时的立即查询也会拿到结果。
- SDK 用 seal 私钥在本机解开结果，交给你的代码。
使用 Swift SDK 时，以上步骤全部封装在 authorize()、pickItem() 等异步方法中；如需自行实现，请参阅 API 参考。
执行模式
| 模式 | 说明 | 状态 |
|---|---|---|
| 模式 1：设备执行 | 你只能发起请求；解密只发生在用户已解锁的设备上，结果密封回传，服务器只见密文 | 唯一可用的模式 |
| 模式 2：服务端库钥 | 用户把整个库的库钥包裹给接入方服务器，接入方可随时直读该库 | 已停止新建：同意卡不再提供，提交 mode: 2 返回 400 mode_retired；既有授权只读兼容 |
获取 client_id
在 MimiKey for Mac 中登记（推荐）
- 登录 MimiKey for Mac，在侧栏点「开发者接入」。
- 点「新建应用」，填写：
- 名称（1–100 个字符）与可选的说明；
- 类型：App 内 SDK 选「公开客户端」；
- 平台（仅用于展示）；
- 回调地址：每行一个，例如
com.example.ai://mimikey/callback； - 可选的品牌色、主页、图标地址。
- 点「登记」。公开客户端只显示
client_id；机密客户端同时显示client_secret，只显示这一次，请立即保存到服务端配置。
在同一页面可以查看授权数量，或「停用」某个应用。停用会立即撤销它的全部授权，不可恢复。
通过 API 登记
持有账号会话令牌时，也可以直接调用 POST /api/oauth/clients，见 API 参考。
回调地址规则
| client 类型 | 允许的回调地址 |
|---|---|
| public | 自定义 scheme（^[a-z][a-z0-9+.-]{1,63}://…，scheme 小写、不含 http/https/mimikey），以及 https 与本机 http |
| confidential | https://…，本机调试可用 http://127.0.0.1… 或 http://localhost… |
- 每个 client 1–10 个回调地址，每个不超过 500 个字符，不允许通配符
*。 - 授权与回调时逐字匹配登记值。
提示 自定义 scheme 被其他 App 抢注不会泄露数据：回调 URL 只携带
code、request_id、state、status，换 token 需要只存在于你 App 里的 PKCE verifier，取结果需要只存在于你 App 钥匙串里的审批私钥和 seal 私钥。
品牌白名单
批准卡顶部的品牌块是你唯一能定制的部分：
| 字段 | 规则 | 卡上的呈现 |
|---|---|---|
name | 1–100 个字符 | 应用名称，出现在卡标题中（例如「{name} 请你选一个条目」） |
brand.logo_url | 必须是 https，不超过 500 个字符 | 圆角方块图标；加载失败时回退为名称首字母 |
brand.color | #RRGGBB | 品牌色点缀（服务器统一存为大写） |
brand.homepage | 网址，不超过 500 个字符 | 只显示域名 |
platforms | 最多 10 个，小写字母、数字、_、- | 仅用于展示 |
brand 中的其他键会被忽略。卡片的结构、按钮文案与语义、过期倒计时和风险提示由 MimiKey 决定，不可定制。
平台规则
- 不得自绘凭据输入界面。 缺少凭据时，唯一允许的做法是发起
create_item请求，让用户在 MimiKey 的安全卡上输入。你的 App 不得以任何形式收集、记录或转发用户输入的凭据。 - 提示信息不得含凭据。
reason、hint、prefill与fields是服务器可见的明文，会原样展示给用户。 - 按用户的决定行事。 遵守撤销与拒绝；收到
refresh_token_reused、grant_revoked或client_disabled时停止自动重试，引导用户重新授权。
违反规则的接入方可能被平台运营方停用：其全部授权立即撤销，后续调用返回 401 client_disabled，深链也会被 MimiKey 拒绝。
下一步
- Swift SDK（iOS / macOS）：五分钟接入。
- SDK 下载与示例 App：下载 SDK，跑通完整示例。
- 批准卡：用户在每一步看到什么。
- API 参考 与错误码：自行实现协议时使用。