> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-postgresql-tls-support.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Managing API keys

> ClickHouse Cloud provides an API utilizing OpenAPI that allows you to programmatically manage your account and aspects of your services.

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 provides an API utilizing OpenAPI that allows you to programmatically manage your account and aspects of your services.

<Note>
  This document covers the ClickHouse Cloud API. For database API endpoints, please see [Cloud Endpoints API](/products/cloud/guides/sql-console/query-endpoints)
</Note>

<Steps>
  <Step title="Open the API Keys page">
    You can use the **API Keys** tab on the left menu to create and manage your API keys.

    <Image img="https://mintcdn.com/private-7c7dfe99-postgresql-tls-support/Y3FUfPsYjGtSTfZD/images/cloud/manage/openapi1.webp?fit=max&auto=format&n=Y3FUfPsYjGtSTfZD&q=85&s=46e2ce2b91d01ba7893a94e7f2e2dbd6" size="sm" alt="API Keys tab" border width="433" height="472" data-path="images/cloud/manage/openapi1.webp" />
  </Step>

  <Step title="Start creating an API key">
    The **API Keys** page will initially display a prompt to create your first API key as shown below. After your first key is created, you can create new keys using the `New API Key` button that appears in the top right corner.

    <Image img="https://mintcdn.com/private-7c7dfe99-postgresql-tls-support/2QCOf7xGnBQgqjDM/images/cloud/manage/openapi2.webp?fit=max&auto=format&n=2QCOf7xGnBQgqjDM&q=85&s=a416b34ce42d51a59cf42e707ddd46fd" size="md" alt="API Keys page" border width="1036" height="466" data-path="images/cloud/manage/openapi2.webp" />
  </Step>

  <Step title="Configure the API key">
    Specify the key name, permissions for the key, and expiration time.

    <Note>
      Permissions align with ClickHouse Cloud [predefined roles](/products/cloud/reference/security/console-roles). The developer role has read-only permissions for assigned services and the admin role has full read and write permissions.
    </Note>

    <Tip>
      **Query API Endpoints**

      To use API keys with [Query API Endpoints](/products/cloud/guides/sql-console/query-endpoints), set Organization Role to `Member` (minimum) and grant Service Role access to `Query Endpoints`.
    </Tip>

    <Image img="https://mintcdn.com/private-7c7dfe99-postgresql-tls-support/2QCOf7xGnBQgqjDM/images/cloud/manage/openapi3.png?fit=max&auto=format&n=2QCOf7xGnBQgqjDM&q=85&s=4ef9735a641b3a8723cf3caa453f4966" size="md" alt="Create API key form" border width="661" height="410" data-path="images/cloud/manage/openapi3.png" />
  </Step>

  <Step title="Add allowed IP addresses">
    To restrict which clients can use the API key, in the **Allow access to this API Key** section, select **Specific locations**. Enter an IP address or CIDR range, such as `203.0.113.1` or `203.0.113.0/24`, and add additional entries as needed.

    Query API endpoints respect API key-level IP allowlists. Because requests are proxied from within ClickHouse's infrastructure, service-level IP allowlists do not apply. See [IP Access Control](/cloud/features/query-api-endpoints#ip-access-control) for details.

    <Image img="https://mintcdn.com/private-7c7dfe99-postgresql-tls-support/ie2pnLZPTjmhniJm/images/cloud/guides/query-endpoints/specific-locations.webp?fit=max&auto=format&n=ie2pnLZPTjmhniJm&q=85&s=a085871a4379f47b8e89bb55cbdbbda8" size="md" alt="Allowed IP addresses configured for an API key" border width="1336" height="1740" data-path="images/cloud/guides/query-endpoints/specific-locations.webp" />

    Click **Generate API Key** when you have finished configuring the key.
  </Step>

  <Step title="Save the API key credentials">
    The next screen will display your Key ID and Key secret. Copy these values and put them somewhere safe, such as a vault. The values won't be displayed after you leave this screen.

    <Image img="https://mintcdn.com/private-7c7dfe99-postgresql-tls-support/2QCOf7xGnBQgqjDM/images/cloud/manage/openapi4.webp?fit=max&auto=format&n=2QCOf7xGnBQgqjDM&q=85&s=c252c154d794d5d7ad92e7fd10c62023" size="md" alt="API key details" border width="653" height="271" data-path="images/cloud/manage/openapi4.webp" />
  </Step>

  <Step title="Authenticate API requests">
    The ClickHouse Cloud API uses [HTTP Basic Authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication) to verify the validity of your API keys. Here is an example of how to use your API keys to send requests to the ClickHouse Cloud API using `curl`:

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

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

  <Step title="Manage existing API keys">
    Returning to the **API Keys** page, you will see the key name, last four characters of the Key ID, permissions, status, expiration date, and creator. You're able to edit the key name, permissions, and expiration from this screen. Keys may also be disabled or deleted from this screen.

    <Note>
      Deleting an API key is a permanent action. Any services using the key will immediately lose access to ClickHouse Cloud.
    </Note>

    <Image img="https://mintcdn.com/private-7c7dfe99-postgresql-tls-support/2QCOf7xGnBQgqjDM/images/cloud/manage/openapi5.webp?fit=max&auto=format&n=2QCOf7xGnBQgqjDM&q=85&s=45cb128654c60f2dd7b671c767c19fb4" size="md" alt="API Keys management page" border width="1092" height="335" data-path="images/cloud/manage/openapi5.webp" />
  </Step>
</Steps>

<h2 id="endpoints">
  Endpoints
</h2>

Refer details on endpoints, refer to the [API reference](/products/cloud/api-reference/organization/get-list-of-available-organizations).
Use your API Key and API Secret with the base URL `https://api.clickhouse.cloud/v1`.