跳到主要内容
印格

API 密钥配置

在控制台创建平台 API Key（前缀 inf_），用于记忆库 REST/MCP 与 AI Gateway 代理。本文说明权限、绑定与请求头用法；端点细节见各产品 API 文档。

平台 Key 与上游 Key

印格 API Key 是团队级访问凭证，由控制台生成并存储哈希值；完整密钥仅在创建时显示一次。它与 Gateway 连接配置中的上游 Gemini / OpenAI Key 不同：后者由 Gateway 在服务端转发，客户端只需携带平台 Key。

本地开发可在 .env 使用 PLATFORM_API_KEYS 占位 Key；生产环境必须使用控制台创建的 inf_ 密钥，env 占位 Key 会被拒绝。

在控制台创建

  1. 登录控制台 → 侧栏「API 密钥」（/dashboard/keys）
  2. 填写名称，便于区分用途（如「Cursor MCP」「CI Gateway」）
  3. 在「权限（多选）」中勾选所需 Scope，或使用下方快捷预设
  4. 若使用 Memory：可选「记忆库访问范围」与「MCP 默认记忆库」
  5. 若使用 Gateway：建议绑定目标 Gateway，限制 Key 只能访问该 /g/<public-id>/…
  6. 点击「生成密钥」，立即复制 inf_… 完整字符串；关闭页面后无法再次查看

→ 控制台 /dashboard/keys

权限（Scope）

每个 Key 可勾选多项 Scope。请求到达对应 API 时，服务端校验 Key 是否包含所需 Scope；缺少时返回 403。

Scope分组说明
gateway:generateGateway调用 Gateway 文本/多模态生成（Gemini generateContent、OpenAI chat 等）
gateway:embedGateway调用 Gateway 向量嵌入接口
gateway:routesGateway解析逻辑路由（model 参数映射到 route_id）
memory:readMemory记忆库检索、GET /atoms、MCP 读工具（search / recall / wake-up / list）
memory:writeMemory写入 Atom、MCP memory_save_atom / memory_correct_atom、POST/PATCH /atoms

快捷预设

预设Scope适用场景
MCP 只读memory:read仅需检索记忆的 Agent（Cursor、Claude Desktop 等）
MCP 读写memory:read + memory:write需要 Agent 主动落盘记忆的典型场景
Gateway 默认gateway:generate + gateway:embed + gateway:routes + memory:readSDK 调用 Gateway，并保留记忆库只读能力

绑定 Gateway（可选）

创建 Key 时可选择绑定团队内某一 Gateway。绑定后该 Key 只能访问该 Gateway 的公开路径；未绑定则可访问同团队任意 Gateway（URL 中的 public-id 仍须正确）。

  • Memory MCP / REST：通常无需绑定 Gateway
  • Gemini SDK baseUrl 指向 /g/<public-id> 时：建议绑定对应 Gateway，降低误用风险
  • 绑定 Key 的团队必须与 Gateway 所属团队一致（跨团队 Key 无效）

记忆库范围与 MCP 默认库

勾选 memory:* Scope 后，可进一步限制 Key 能访问的记忆库，并指定 MCP 连接的默认库。

  • 记忆库访问范围：默认「全部记忆库」；勾选「仅指定记忆库」后，REST 与 MCP 均只能访问所选库
  • MCP 默认记忆库：未指定时跟随团队「MCP Agent 策略」中的默认库；指定后该 Key 的 MCP 连接固定使用该库
  • 若限制了访问范围，MCP 默认库下拉仅显示允许范围内的库
  • 创建后可在密钥列表中修改 MCP 默认库与访问范围（无需重新生成 Key）

在请求中携带 Key

服务端按以下顺序解析 Key：x-goog-api-key → URL ?key= → Authorization: Bearer → X-API-Key。

记忆库 REST / MCP

  • Authorization: Bearer inf_xxxxxxxx（推荐）
  • X-API-Key: inf_xxxxxxxx

Gateway（Gemini 兼容）

  • x-goog-api-key: inf_xxxxxxxx

Gateway（OpenAI 兼容）

  • Authorization: Bearer inf_xxxxxxxx

MCP Streamable HTTP

  • Authorization: Bearer inf_xxxxxxxx
  • Accept: application/json, text/event-stream（必需）
  • Content-Type: application/json

MCP 配置示例

{
  "mcpServers": {
    "engra-memory": {
      "url": "https://mcp.engra.ai/api/v1/memory/mcp",
      "headers": {
        "Authorization": "Bearer inf_xxxxxxxx",
        "Accept": "application/json, text/event-stream",
        "Content-Type": "application/json"
      }
    }
  }
}

安全建议

  • 按最小权限原则勾选 Scope；只读 Agent 不要授予 memory:write
  • 为不同环境/客户端创建独立 Key，便于吊销与审计
  • 勿将 Key 提交到版本库；使用环境变量或密钥管理服务
  • 人员离职或 Key 泄露时，在控制台立即「吊销」
  • 列表中的 key_prefix（前 12 字符）仅用于识别，不能用于鉴权

常见错误

HTTP原因
401 unauthorized未传 Key、Key 无效、已吊销或已过期
403 forbiddenKey 有效但缺少所需 Scope（如用只读 Key 调用 POST /atoms）
403（Gateway 绑定）Key 绑定了 Gateway A，却请求 Gateway B 的 /g/<public-id>/…
406（MCP）MCP 客户端未设置 Accept: application/json, text/event-stream

谁可以管理密钥

API 密钥页面受团队角色权限控制：

角色查看创建 / 吊销
admin✓✓
member✓✓
viewer✓✗

相关文档