> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orriven.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API 密钥

> 生成、使用与吊销开发者密钥——一把密钥等于对一个业务单元的完整 API 权限,Secret 只显示一次。

「API 密钥」页面在业务单元导航中,位于「成员」与「设置」之间。一把密钥是一对凭证:

* **Key ID**(`ok_…`)——密钥的公开名字。随时可见,写进日志和工单都安全;它用来识别密钥,但不能用来调用 API。
* **Secret**(`osk_…`)——真正的凭证。**只在创建成功后显示一次**。Orriven 只保存它的哈希:Secret 一旦丢失就无法找回——只能生成新密钥、吊销旧的。

<Warning>
  一把密钥可以读写其业务单元内的**全部内容**。请像对待密码一样对待 Secret:放在服务端的密钥管理里,绝不要放进浏览器、移动 App 或代码仓库。
</Warning>

## 谁能管理密钥

只有组织的\*\*所有者(Owner)和管理员(Admin)\*\*能查看、生成、吊销密钥。策划及其他角色没有入口——密钥的能力范围大于他们本人的权限,所以发放密钥是管理员的决定。

## 生成密钥

<Steps>
  <Step title="打开「API 密钥」,点「生成密钥」">
    用要接入的系统给密钥命名——「CRM 同步」「签到闸机」。名字只为你自己记账。
  </Step>

  <Step title="从横幅里复制 Secret">
    完整 Secret 会在一条带复制按钮的横幅中出现一次。横幅头几秒无法关闭——那就是你的复制窗口。离开页面后,列表里只剩前缀(`osk_1a2b…`)。
  </Step>

  <Step title="调用 API">
    每个请求都以 Bearer 令牌携带 Secret:

    ```bash theme={null}
    curl -H "Authorization: Bearer osk_…" "$BASE/v1/events"
    ```
  </Step>
</Steps>

## 密钥列表

每行显示密钥名称、Key ID、Secret 前缀、钉住的 [API 版本](/zh/developers/versioning)、创建人、最近使用时间和状态:**有效**、**已吊销**或**已过期**。「最近使用」随集成的调用而更新——部署之后仍显示*从未使用*,说明你的集成没有真正打到 Orriven。

## 吊销

吊销**立即生效**:使用该密钥的每个请求都会开始收到与未知密钥完全相同的 `401`。吊销不可撤销,吊销后的密钥保留在列表中作为记录。轮换凭证的正确姿势:先生成新密钥、把集成切换过去,再吊销旧的——零停机。

## 注意事项

* **Secret 只出现一次。** 列表里没有,任何 API 响应里没有,客服也拿不到。丢了 = 换新密钥。
* **一把密钥,一个业务单元。** 密钥永远看不到其他单元的数据;请求其他单元的活动,得到的回答与该活动不存在时完全一样。
* **密钥的一切动作都有审计。** 生成与吊销记入[审计日志](/zh/organization/audit-logs),密钥执行的每次写操作也以该密钥为操作者留痕。
* **无效就是无效。** 缺失、写错、已吊销、已过期的 Secret 得到完全相同的 `401` ——响应永远不会透露某个凭证是否存在过。

## 相关页面

<CardGroup cols={2}>
  <Card title="快速上手" icon="rocket" href="/zh/developers/quickstart">
    用新密钥发出第一批请求。
  </Card>

  <Card title="成员与角色" icon="users" href="/zh/organization/members-roles">
    为什么密钥管理只属于所有者/管理员。
  </Card>
</CardGroup>