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

# API Key 如何创建、保存、轮换和撤销？

> 老张API的 API Key 怎么创建和安全保存：用 IP 白名单、可用模型、授权额度和过期时间限制令牌，泄露或出现来源不明的调用时如何停用、排查和轮换，并区分 API Key 与系统 AccessToken。

在[令牌管理页面](https://api.laozhang.ai/token)创建和管理 API Key。一个令牌能花掉的上限就是账户余额，所以每个令牌都应该加上授权额度等限制，并且只保存在服务器端；怀疑泄露时立即停用，再查调用日志。

本页依据 [老张API用户协议](https://www.laozhang.ai/zh-cn/terms) 与 [数据政策](https://www.laozhang.ai/zh-cn/data-policy) 整理，最后核对日期为 **2026 年 10 月 5 日**。控制台字段和权限选项以当前页面为准。

## 创建 API Key

1. 登录老张API控制台；
2. 打开[令牌管理](https://api.laozhang.ai/token)；
3. 按当前控制台要求选择名称、分组、额度或其他可用限制；
4. 创建后立即复制并保存到安全位置；
5. 使用最小请求验证端点、模型和计费分组。

<Warning>
  不要在文档、工单或群聊中发送完整 API Key。支持团队排查时通常只需要账户、时间、模型、错误和脱敏后的密钥标识。
</Warning>

## 推荐保存方式

### 环境变量

```bash theme={null}
export LAOZHANG_API_KEY="替换为你的老张API密钥"
```

在 Python 中读取环境变量（需先执行 `pip install openai`）：

```python theme={null}
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["LAOZHANG_API_KEY"],
    base_url="https://api.laozhang.ai/v1",
)
```

生产环境优先使用云密钥管理服务、容器 Secret 或部署平台的加密环境变量。不要通过 `echo`、调试日志或异常信息输出密钥。

## 给令牌设置限制

创建或编辑令牌时，可以设置以下四项限制：

| 限制 | 作用 | 适合 |
| - | - | - |
| 授权额度 | 关闭无限额度后，令牌最多只能花掉设定的金额 | 所有令牌，测试令牌必设 |
| IP 白名单 | 只有来自指定 IP 或网段的请求能使用该令牌 | 出口 IP 固定的生产服务器 |
| 可用模型 | 令牌只能调用列出的模型；留空表示不限制 | 只跑固定任务、交给他人使用的令牌 |
| 过期时间 | 到期后令牌自动失效 | 临时任务、给 AI 工具用的令牌 |

* **授权额度**是最该设置的一项：开着无限额度的令牌一旦泄露，损失上限就是全部余额。授权额度只是消耗上限，不会预先冻结余额；多个令牌共享同一个账户余额。
* **IP 白名单**要填服务器的公网出口 IP，可以填单个 IP 或 CIDR 网段，例如 `203.0.113.0/24`。家用宽带、办公网络的出口 IP 会变化，开启后 IP 一变调用就会全部失败，这类环境改用授权额度控制风险。
* **可用模型**填写后，令牌调用其他模型会被拒绝。模型 ID 要与[模型与价格总表](/models)完全一致；日常自用和探索测试一般不设置，以免每次换模型都要回来修改。

开发、测试和生产分别使用不同令牌，不同服务或自动化任务也各用一个，并起有辨识度的名称，例如 `prod-image-service`。出问题时可以只停用其中一个，不影响其他业务。不要在浏览器、移动端或公开客户端中嵌入服务器 API Key。

## 不要让密钥出现在这些地方

* **代码仓库**：密钥提交进 Git 后，即使删除文件，仍留在提交历史里。把 `.env` 加入 `.gitignore`，提交前扫描一遍：

  ```bash theme={null}
  grep -rnE '(^|[^A-Za-z0-9])sk-[A-Za-z0-9]{10,}' .
  ```

* **文档、截图和日志**：控制台截图、终端录屏和报错日志都可能带着完整密钥，示例里统一用占位符。公开仓库会被自动程序持续扫描，泄露的密钥可能很快被利用。

* **AI 工具的对话**：粘贴进 AI 编程工具的密钥通常会以明文留在本机会话记录和文件快照里。给 AI 工具单独建临时令牌，设小额度和较短的过期时间，用完即删，不要交出生产密钥。

## 轮换和撤销

出现以下情况时应立即轮换或撤销：

* 密钥进入 Git、日志、截图、工单或公开消息；
* 发现来源不明的调用或余额变化；
* 员工、外包或系统权限发生变化；
* 依赖、服务器或部署凭证被入侵；
* 支持或安全团队要求采取措施。

安全轮换流程：

1. 创建新密钥并在受控环境验证；
2. 更新服务端 Secret；
3. 观察新密钥调用结果；
4. 撤销旧密钥；
5. 检查[调用日志](/faq/call-logs)和受影响时间范围。

固定轮换周期应由企业自己的风险、审计和运维策略决定，文档不承诺统一周期或无限额度。

## 排查来源不明的调用

发现某个令牌有你不认识的调用时：

<Steps>
  <Step title="先找这个密钥给过谁">
    复制该令牌的密钥，在聊天记录、代码仓库及提交历史、部署平台和 CI 的环境变量里全局搜索。多数“莫名调用”是某处遗留的旧配置仍在运行。
  </Step>

  <Step title="找不到就直接停用">
    在[令牌管理](https://api.laozhang.ai/token)停用该令牌。令牌相互独立，停用一个不影响账户下的其他令牌；确认需要后再新建一个替换。
  </Step>

  <Step title="用调用日志锁定来源">
    在[调用日志](https://api.laozhang.ai/log)按该令牌筛选，看调用的模型、时间段和来源 IP。重点关注你没用过的模型、非工作时间的调用和与业务量不符的请求数。
  </Step>

  <Step title="加固账户">
    修改账户密码，减少能登录控制台的人；员工只需要查询用量时，不必给控制台权限。
  </Step>
</Steps>

## API Key 与系统 AccessToken

普通模型调用使用 API Key。账户级余额查询等管理接口可能使用不同的系统 AccessToken，不能互换。需要账户级查询时，请查看[余额查询 API](/api-capabilities/balance-query)，并按该页面的权限边界操作。

## 需要支持时提供什么

联系支持时提供账户、密钥创建时间、脱敏后的密钥前后缀、异常调用时间、模型和错误信息。不要发送完整 API Key；如果已经公开，应先撤销或轮换，再继续排查。

## 相关文档

* [如何查看调用日志](/faq/call-logs)
* [提示 API Key 无效或 404 怎么办](/faq/invalid-api-key)
* [为什么还有余额但调用失败](/faq/balance-insufficient)
* [老张API如何处理数据与日志](/faq/data-security)
* [老张API用户协议](https://www.laozhang.ai/zh-cn/terms)


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