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

# 管理 API 密钥

> 创建、保存和管理接口AI API 密钥，了解密钥有效期与访问控制

## API 密钥概述

调用接口AI 的 API 时，需要在请求头中使用 **Bearer 认证方式**进行 API 访问认证，例如："Authorization: Bearer \{API 密钥}"。

每个 API 密钥都以 `sk_` 开头，是一串随机字符串。密钥的有效期在创建时设置，详见[密钥有效期](#密钥有效期)。

您可以前往[密钥管理](https://jiekou.vip/settings/key-management)页面查看和管理您的 API 密钥。

<Note>
  密钥的创建与删除仅在控制台提供，OpenAPI 不包含创建或删除密钥的接口，也不支持通过 OpenAPI 配置或修改密钥的过期时间。OpenAPI 提供单个密钥网络访问策略的读写，详见[查询 API Key 网络访问策略](/docs/models/reference-key-get-ip-access-policy)。
</Note>

## 创建 API 密钥

1. 进入[密钥管理](https://jiekou.vip/settings/key-management)页面，单击「+创建」。

2. 输入密钥名称，选择密钥有效期，然后单击「确认」。

3. 保存密钥。

   <Warning>
     API 密钥创建后无法再次查看，请妥善保存您的密钥。如果遗失，您需要生成新的密钥。
   </Warning>

## 管理 API 密钥

对于已有的 API 密钥，支持以下操作：

* 修改：单击对应密钥的编辑按钮，输入新的密钥名称，单击「确认」即可完成修改。
* 删除：单击对应密钥的删除按钮，确认后即可删除。

<Warning>
  密钥一经删除即刻失效且不可恢复，使用该密钥的所有调用都会返回鉴权失败（HTTP 401）。删除前请确认没有线上业务仍在使用它。
</Warning>

## 密钥有效期

创建 API 密钥时可以设置过期时间，四档可选：**永久、90 天、30 天、24 小时**。

<Note>
  过期时间在创建时设定，**创建后不可修改**，也不支持续期或立即过期。选择「永久」时，密钥长期有效，泄露后风险更高，请谨慎使用。过期时间不支持通过 OpenAPI 配置或修改，只能在控制台创建密钥时设置。
</Note>

密钥的过期状态在密钥列表和设置页统一展示为三种：

| 状态 | 含义 |
| :- | :- |
| 生效中 | 密钥在有效期内，可正常调用。 |
| 即将过期 | 距离过期 7 天内（黄色提示），24 小时内进一步标红。 |
| 已过期 | 已超过过期时间，调用被拒绝。 |

已过期的密钥调用会被拒绝，但配置仍可查看，删除入口保留。过期不等于禁用；需要恢复调用只能创建新密钥。如需在到期前停用某个密钥，可在控制台直接删除它，删除后立即失效。

## 访问控制

您可以分别限制单个 API 密钥可调用的模型和允许的来源 IP：

<CardGroup cols={2}>
  <Card title="模型访问" href="/docs/support/api-key-model-access">
    限定密钥可调用的模型，并了解模型下线与调用被拒时的处理方式。
  </Card>

  <Card title="网络访问" href="/docs/support/api-key-network-access">
    限定允许的 IPv4 地址或 CIDR 网段，降低密钥泄露后的滥用风险。
  </Card>
</CardGroup>

## 用量与预算

接口AI 的预算按团队成员设置，同一成员创建的所有 API 密钥共享该成员的预算池。成员预算用尽后，该成员名下的密钥都会暂停调用。配置方式和预算类型详见[预算管理](/docs/support/budgets)。

## 环境变量配置

建议把 API 密钥配置到环境变量，避免在代码里硬编码密钥，降低泄漏风险。代码从环境变量读取密钥，例如 `os.environ["JIEKOU_API_KEY"]`。

### 临时变量与永久变量

* **临时变量**：只在当前终端会话生效，关闭终端后失效，适合临时测试。
* **永久变量**：写入 shell 配置文件或系统环境变量，新开的终端和重启后仍然生效，适合长期使用。

下面按操作系统给出设置方法（以变量名 `JIEKOU_API_KEY` 为例）。

<Tabs>
  <Tab title="Linux">
    临时变量（仅当前终端会话有效）：

    ```bash theme={null}
    export JIEKOU_API_KEY="sk_你的密钥"
    ```

    永久变量（写入 `~/.bashrc`，对 bash 生效；zsh 请写入 `~/.zshrc`）：

    ```bash theme={null}
    echo 'export JIEKOU_API_KEY="sk_你的密钥"' >> ~/.bashrc
    source ~/.bashrc
    ```

    验证是否设置成功：

    ```bash theme={null}
    echo $JIEKOU_API_KEY
    ```
  </Tab>

  <Tab title="macOS">
    临时变量（仅当前终端会话有效）：

    ```bash theme={null}
    export JIEKOU_API_KEY="sk_你的密钥"
    ```

    永久变量（macOS 默认 shell 为 zsh，写入 `~/.zshrc`）：

    ```bash theme={null}
    echo 'export JIEKOU_API_KEY="sk_你的密钥"' >> ~/.zshrc
    source ~/.zshrc
    ```

    验证是否设置成功：

    ```bash theme={null}
    echo $JIEKOU_API_KEY
    ```
  </Tab>

  <Tab title="Windows">
    临时变量（仅当前 PowerShell 会话有效）：

    ```powershell theme={null}
    $env:JIEKOU_API_KEY = "sk_你的密钥"
    ```

    永久变量（写入用户级环境变量，需新开终端才生效）：

    ```powershell theme={null}
    setx JIEKOU_API_KEY "sk_你的密钥"
    ```

    验证是否设置成功（新开一个终端后执行）：

    ```powershell theme={null}
    echo $env:JIEKOU_API_KEY
    ```
  </Tab>
</Tabs>

### 设置了变量但代码仍找不到

如果设置后代码依然读取不到密钥，按以下几种情况排查：

* **只设了临时变量**：`export` 或 `$env:` 只对当前终端会话有效，换个终端或重启后就没了。需要长期生效请改用永久变量（`~/.bashrc` / `~/.zshrc` / `setx`）。
* **改了配置但没重新加载**：写入 `~/.bashrc` / `~/.zshrc` 后，需要 `source` 对应文件或重开终端；IDE 内置终端通常要重启 IDE 才会加载新变量。
* **进程管理器不继承用户变量**：用 systemd、supervisor、PM2 等托管服务时，不会自动继承你登录 shell 的环境变量，需要在各自的服务配置里单独声明。
* **sudo 不继承当前环境**：`sudo` 默认使用干净的环境，读不到当前用户的变量。需要传递时使用 `sudo -E`，或在 root 环境下单独配置。

## 安全最佳实践与泄露应急

API 密钥等同于账户凭证，任何持有它的人都能以您的身份调用 API 并产生费用。请遵循以下实践：

* **用环境变量存储**：把密钥放进环境变量或密钥管理服务，不要硬编码进源代码。
* **不要提交到代码仓库**：避免把密钥写进代码、配置文件后提交到 Git；对外分享代码或截图前先移除密钥。
* **不要放进前端**：不要在浏览器端、移动 App 等客户端代码中直接使用密钥，这些环境的密钥可被他人提取。请通过您自己的后端中转调用。
* **一环境一密钥**：为不同环境（生产、测试、CI）和不同用途分配独立密钥，便于按需停用和排查，互不影响。
* **用模型访问和网络访问收敛权限**：结合[模型访问](/docs/support/api-key-model-access)限定单个密钥可调用的模型，结合[网络访问](/docs/support/api-key-network-access)限定允许的来源 IP，缩小单个密钥的影响面。
* **定期轮换**：定期更换密钥。轮换时先创建新密钥、切换业务使用新密钥、在生产验证无误后再删除旧密钥，实现零停机切换。

### 密钥泄露后的处理

如果怀疑某个密钥已泄露（例如误提交到公开仓库、出现在日志或截图中）：

1. 立即进入[密钥管理](https://jiekou.vip/settings/key-management)页面删除该密钥，使其失效。
2. 创建一个新密钥，更新到所有使用该密钥的业务中。为新密钥配置[网络访问](/docs/support/api-key-network-access)，只允许你的业务出口 IP，降低再次泄露后的风险。
3. 通过[操作审计](/docs/support/audit-log)检查是否存在异常操作，通过[预算管理](/docs/support/budgets)确认消费是否异常。
4. 如需收紧团队成员对密钥的管理权限，参见[团队管理](/docs/support/team)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.