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

# 管理 API Key

> ClickHouse Cloud 提供了基于 OpenAPI 的 API，您可以通过编程方式管理您的账户以及服务的各个方面。

export const Image = ({img, alt, size = "lg"}) => {
  const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
  return <div className={`ch-image-${normalizedSize}`}>
      <Frame>
        <img src={img} alt={alt} />
      </Frame>
    </div>;
};

ClickHouse Cloud 提供基于 OpenAPI 的 API，便于您以编程方式管理账户及服务的各个方面。

<Note>
  本文档介绍的是 ClickHouse Cloud API。有关数据库 API 端点，请参阅 [Cloud Endpoints API](/docs/zh/products/cloud/guides/sql-console/query-endpoints)
</Note>

<Steps>
  <Step title="打开 API Keys 页面">
    您可以使用左侧菜单中的 **API Keys** 选项卡创建和管理 API Key。

    <Image img="https://mintcdn.com/private-7c7dfe99/REHSqgCLT_igIuJP/images/cloud/manage/openapi1.webp?fit=max&auto=format&n=REHSqgCLT_igIuJP&q=85&s=4b5e224e02e9995b15f410c0b53cc5e7" size="sm" alt="API Keys 选项卡" border width="433" height="472" data-path="images/cloud/manage/openapi1.webp" />
  </Step>

  <Step title="开始创建 API Key">
    **API Keys** 页面最初会显示提示，指导您创建第一个 API Key，如下所示。创建第一个密钥后，您可以使用右上角显示的 `New API Key` 按钮创建新密钥。

    <Image img="https://mintcdn.com/private-7c7dfe99/REHSqgCLT_igIuJP/images/cloud/manage/openapi2.webp?fit=max&auto=format&n=REHSqgCLT_igIuJP&q=85&s=3ad9d02d51c9ac4c8b0649027ccf61ec" size="md" alt="API Keys 页面" border width="1036" height="466" data-path="images/cloud/manage/openapi2.webp" />
  </Step>

  <Step title="配置 API Key">
    指定密钥名称、密钥权限和过期时间。

    <Note>
      权限与 ClickHouse Cloud 的[预定义角色](/docs/zh/products/cloud/reference/security/console-roles)一致。developer 角色对已分配的服务具有只读权限，admin 角色具有完整的读写权限。
    </Note>

    <Tip>
      **查询 API 端点**

      要将 API Key 用于 [Query API Endpoints](/docs/zh/products/cloud/guides/sql-console/query-endpoints)，请将 Organization Role 设置为 `Member` (最低要求) ，并为 Service Role 授予 `Query Endpoints` 的访问权限。
    </Tip>

    <Image img="https://mintcdn.com/private-7c7dfe99/C7EtYbvQvbHPGmL5/images/cloud/manage/openapi3.png?fit=max&auto=format&n=C7EtYbvQvbHPGmL5&q=85&s=d85d50665cb229cce53ba16a82a27cd1" size="md" alt="创建 API Key 表单" border width="661" height="410" data-path="images/cloud/manage/openapi3.png" />
  </Step>

  <Step title="添加允许的 IP 地址">
    要限制哪些客户端可以使用该 API Key，请在 **Allow access to this API Key** 部分中选择 **Specific locations**。输入一个 IP 地址或 CIDR 范围，例如 `203.0.113.1` 或 `203.0.113.0/24`，并根据需要添加更多条目。

    查询 API 端点遵循 API Key 级别的 IP 允许列表。由于请求是从 ClickHouse 基础设施内部代理的，因此服务级别的 IP 允许列表不适用。详情请参阅 [IP Access Control](/docs/zh/cloud/features/query-api-endpoints#ip-access-control)。

    <Image img="https://mintcdn.com/private-7c7dfe99/A68-kVUDkVcT2W3b/images/cloud/guides/query-endpoints/specific-locations.webp?fit=max&auto=format&n=A68-kVUDkVcT2W3b&q=85&s=db3d75c39aa5c3e73bc0d23dad7ae25c" size="md" alt="为 API Key 配置的允许 IP 地址" border width="1336" height="1740" data-path="images/cloud/guides/query-endpoints/specific-locations.webp" />

    完成密钥配置后，点击 **Generate API Key**。
  </Step>

  <Step title="保存 API Key 凭据">
    下一个界面将显示您的 Key ID 和 Key secret。请复制这些值并妥善保存在安全的位置，例如密钥保管库。离开此界面后，这些值将不会再次显示。

    <Image img="https://mintcdn.com/private-7c7dfe99/REHSqgCLT_igIuJP/images/cloud/manage/openapi4.webp?fit=max&auto=format&n=REHSqgCLT_igIuJP&q=85&s=5872535bb69a2299c88f38c627ead497" size="md" alt="API Key 详细信息" border width="653" height="271" data-path="images/cloud/manage/openapi4.webp" />
  </Step>

  <Step title="对 API 请求进行身份验证">
    ClickHouse Cloud API 使用 [HTTP 基本身份验证](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication) 来验证您的 API Key 是否有效。以下示例展示了如何使用 API Key 通过 `curl` 向 ClickHouse Cloud API 发送请求：

    ```bash theme={null}
    $ KEY_ID=mykeyid
    $ KEY_SECRET=mykeysecret

    $ curl --user $KEY_ID:$KEY_SECRET https://api.clickhouse.cloud/v1/organizations
    ```
  </Step>

  <Step title="管理现有 API Key">
    返回 **API Keys** 页面后，您将看到密钥名称、Key ID 的后四位字符、权限、状态、到期日期以及创建者。您可以在此界面编辑密钥名称、权限和过期时间，也可以在此界面禁用或删除密钥。

    <Note>
      删除 API Key 是永久性操作。任何使用该密钥的服务都将立即失去对 ClickHouse Cloud 的访问权限。
    </Note>

    <Image img="https://mintcdn.com/private-7c7dfe99/REHSqgCLT_igIuJP/images/cloud/manage/openapi5.webp?fit=max&auto=format&n=REHSqgCLT_igIuJP&q=85&s=e81ed237b99933a115f931acc919c8f8" size="md" alt="API Keys 管理页面" border width="1092" height="335" data-path="images/cloud/manage/openapi5.webp" />
  </Step>
</Steps>

<div id="endpoints">
  ## 端点
</div>

有关端点的详细信息，请参阅 [API 参考文档](/docs/zh/products/cloud/api-reference/organization/get-list-of-available-organizations)。
请使用您的 API Key 和 API Secret，base URL 为 `https://api.clickhouse.cloud/v1`。