跳到主要内容
版本：26.x

API Keys

API Key 是访问 SelectDB Cloud Management API 的程序化凭证，可用于脚本、CI/CD 流水线或第三方集成。其管控权限由所选控制台角色决定，不能用于直接连接数据库或执行 SQL；访问数据库仍需使用数据库凭据。

登录 SelectDB Cloud 控制台，切换到目标组织，在组织左侧导航栏单击 API Keys。API Key 属于创建时选择的组织，创建前请确认组织及程序需要的管控权限。

创建 API Key​

  1. 在 API Keys 页面单击 创建 API key。组织尚无 API Key 时，页面显示 暂无 API key，可从空状态区域的同名按钮开始创建。

  2. 在 新建 API key 对话框中配置以下参数。

    配置项说明
    名称必填，最多 128 个字符，用于标识凭证的用途。
    角色必填，从当前组织的预置或自定义角色中选择一个。表单显示角色名称和描述，按程序所需的管控操作分配权限，角色说明参见 组织角色。角色描述中涉及的数据库权限不代表 API Key 可直接访问数据库。
    过期时间默认 30 天，还可选择 90 天、1 年、自定义 或 永不过期。选择自定义时，按 YYYY-MM-DD HH:mm:ss 格式填写到期时间，并按字段旁显示的时区理解该时间。建议设置晚于当前时间的到期时间。

  3. 单击 确认，创建 API Key。

  4. 在 API key 创建成功 对话框中，立即通过 复制 API key 或 下载 API key 保存完整凭证，然后单击 完成。

完整 API Key 仅在创建成功时展示一次，关闭后无法再次查看。下载得到包含 apiKey 字段的 JSON 文件，应与完整 Key 一样妥善保管。列表中的 ID 仅用于识别凭证，不能单独用于认证；如未保存完整 Key，需创建替代凭证。

完成后，返回列表核对新 Key 的名称、角色和状态。建议为不同程序分别创建 Key，便于区分用途和独立停用。

查看 API Key​

列表展示当前组织的 API Key。在 按名称或 ID 搜索 中输入关键字查找凭证，或将 全部状态 切换为 已启用、已禁用 或 已过期。可通过列表的刷新按钮重新获取记录，并使用分页浏览更多 Key。

字段说明
名称 / ID名称用于标识用途；ID 用于在日志中识别 API Key。单击 ID 旁的复制图标可复制标识，但不能用它代替完整 Key 进行认证。部分历史记录的 ID 会缩略显示。
角色API Key 绑定的控制台角色。
状态已启用、已禁用 或 已过期。
创建时间API Key 的创建时间。
最近使用时间API Key 最近一次使用的时间，没有使用记录时显示 -。
操作启用或禁用开关，以及 编辑 和 删除 图标。

时间列标题显示当前时区。过期时间可在编辑对话框中查看和调整。

管理 API Key​

编辑​

  1. 在目标行的 操作 列单击 编辑 图标，打开 编辑 API key 对话框。
  2. 按需调整 名称、角色 或 过期时间。设置了到期时间的 Key 会以 自定义 显示具体时间，可在此核对。
  3. 单击 保存，返回列表核对名称和角色；如修改了到期时间，可再次打开编辑对话框核对。

变更角色会改变使用该 Key 的程序可执行的管控操作，保存前应确认相关程序所需权限。只修改名称或角色时，原到期时间保持不变；选择 30 天、90 天 或 1 年 并保存时，到期时间从本次修改时刻重新计算。

启用或禁用​

在目标行的 操作 列，通过开关启用或禁用 API Key，操作后核对 状态 列：

  • 禁用：暂停该凭证的 API 访问，可用于临时停止相关程序的访问。
  • 启用：恢复未过期且已禁用凭证的访问。

禁用会影响所有使用该 Key 的程序。已过期凭证的开关不可用，不能直接通过开关恢复访问。

删除​

  1. 在目标行的 操作 列单击 删除 图标。
  2. 在 删除 API key 提示中核对凭证名称及访问中断的影响。
  3. 单击 确认 删除，不执行时单击 取消。

控制台不提供删除后的恢复入口，所有使用该 Key 的程序将无法继续通过它访问 SelectDB Cloud。

更换凭证​

  1. 按程序所需权限创建新 Key，保存完整凭证。
  2. 在相关程序的凭据配置中替换 Key，并验证 API 调用正常。
  3. 禁用旧 Key，确认相关程序已完成切换后，再删除旧 Key。

使用管控 API​

SelectDB Cloud Management API 的基础地址为 https://api.selectdb.com，公开接口位于 /v1 下。在每个请求的 X-API-Key 请求头中携带完整 API Key：

X-API-Key: <your-api-key>

请求能否执行取决于 Key 所属组织、绑定角色、启用状态和过期时间。请将完整 Key 保存在程序的凭据配置中，避免将其写入公开代码或日志。

例如，将完整 Key 通过程序运行环境注入 SELECTDB_API_KEY 后，使用以下只读请求查看仓库列表：

curl --request GET 'https://api.selectdb.com/v1/warehouses?page=1&size=20' \
  --header "X-API-Key: ${SELECTDB_API_KEY}"

写请求还需按接口规范携带 RequestId 幂等请求头。完整接口列表、权限要求和请求与响应结构，参见 SelectDB Cloud Management API Reference。

相关文档​