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

# API Key Authentication

> Create and use API keys to authenticate with the Keyword Insights API

API keys provide a simple, long-lived way to authenticate with the Keyword Insights public API. Unlike Bearer tokens (which expire), API keys remain valid until you delete them — making them ideal for scripts, integrations, and automated workflows.

<Info>
  API key access is available on **Professional** and **Premium** plans. If you're on a different plan, you'll be prompted to upgrade when attempting to create an API key.
</Info>

### Creating an API Key

1. Log in to your [Keyword Insights dashboard](https://app.keywordinsights.ai).
2. Navigate to **API Keys** from the left sidebar menu.
3. Click the **Create API key** button.
4. Enter a descriptive name for the key (e.g. "Python scripts", "N8N integration").
5. Click **Create**.

Once created, your API key will be displayed **once**. Copy it immediately and store it in a secure location — you will not be able to see the full key again.

Your key will look like this:

```
kwi_sk_aBcDeFgHiJkLmNoPqRsTuVwXyZ1234567890abc
```

After you close the modal, the key list will show only the prefix (e.g. `kwi_sk_aBcDe...`) along with the creation date and last used date.

### Using the API Key

Pass your API key in the `X-API-Key` header with every request:

<CodeGroup>
  ```python Python theme={null}
  import requests

  API_KEY = "kwi_sk_your_api_key_here"
  BASE_URL = "https://api.keywordinsights.ai"

  response = requests.get(
      f"{BASE_URL}/api/user/",
      headers={"X-API-Key": API_KEY},
  )

  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const API_KEY = "kwi_sk_your_api_key_here";
  const BASE_URL = "https://api.keywordinsights.ai";

  async function getUser() {
    const response = await fetch(`${BASE_URL}/api/user/`, {
      headers: { "X-API-Key": API_KEY },
    });

    const data = await response.json();
    console.log(data);
  }

  getUser();
  ```
</CodeGroup>

<Warning>
  Treat your API key like a password. Do not commit it to version control or share it publicly. Use environment variables to store it securely.
</Warning>

### Storing the Key Securely

We recommend loading your API key from an environment variable:

```bash theme={null}
export KWI_API_KEY="kwi_sk_your_api_key_here"
```

Then in Python:

<CodeGroup>
  ```python Python theme={null}
  import os

  API_KEY = os.environ["KWI_API_KEY"]
  ```

  ```javascript JavaScript theme={null}
  const API_KEY = process.env.KWI_API_KEY;
  ```
</CodeGroup>

### Example: Create a Clustering Order

<CodeGroup>
  ```python Python theme={null}
  import os
  import requests

  API_KEY = os.environ["KWI_API_KEY"]
  BASE_URL = "https://api.keywordinsights.ai"

  payload = {
      "project_name": "My clustering project",
      "keywords": [
          "keyword clustering",
          "keyword research",
          "topical authority",
      ],
      "search_volumes": [2300, 3210, 5500],
      "language": "en",
      "location": "United States",
      "device": "desktop",
      "clustering_method": "volume",
      "grouping_accuracy": 4,
      "hub_creation_method": "medium",
      "insights": ["cluster", "rank", "context"],
      "url": "https://example.com",
      "folder_id": "<your_folder_id>",
  }

  response = requests.post(
      f"{BASE_URL}/api/keywords-insights/order/",
      headers={"X-API-Key": API_KEY},
      json=payload,
  )

  order = response.json()
  print(order)
  ```

  ```javascript JavaScript theme={null}
  const API_KEY = process.env.KWI_API_KEY;
  const BASE_URL = "https://api.keywordinsights.ai";

  const payload = {
    project_name: "My clustering project",
    keywords: [
      "keyword clustering",
      "keyword research",
      "topical authority",
    ],
    search_volumes: [2300, 3210, 5500],
    language: "en",
    location: "United States",
    device: "desktop",
    clustering_method: "volume",
    grouping_accuracy: 4,
    hub_creation_method: "medium",
    insights: ["cluster", "rank", "context"],
    url: "https://example.com",
    folder_id: "<your_folder_id>",
  };

  async function createOrder() {
    const response = await fetch(`${BASE_URL}/api/keywords-insights/order/`, {
      method: "POST",
      headers: {
        "X-API-Key": API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(payload),
    });

    const order = await response.json();
    console.log(order);
  }

  createOrder();
  ```
</CodeGroup>

The response will contain an `order_id` that you'll use to retrieve results once the order is processed.

### Managing API Keys

You can manage your API keys from the dashboard at any time:

* **View keys** — see all active keys with their prefix, creation date, and last used date.
* **Delete keys** — revoke a key immediately. Any application using that key will lose access.

To delete a key, click the trash icon next to the key and confirm the deletion.

<Info>
  Deleting an API key is immediate and permanent. Make sure no active integrations depend on the key before deleting it.
</Info>

### API Key vs. Bearer Token (Deprecated)

|                   | API Key (Recommended)             | Bearer Token (Deprecated)           |
| ----------------- | --------------------------------- | ----------------------------------- |
| **How to obtain** | Dashboard → API Keys              | Login endpoint or browser dev tools |
| **Header**        | `X-API-Key: kwi_sk_...`           | `Authorization: Bearer eyJ...`      |
| **Expires**       | Never (until deleted)             | After a set period                  |
| **Best for**      | Scripts, integrations, automation | —                                   |

<Warning>
  **Bearer token authentication is deprecated.** If you are currently using Bearer tokens, we strongly recommend migrating to API keys. Bearer tokens will continue to work for now, but may be removed in a future update.
</Warning>

### Migrating from Bearer Tokens

If you have existing code using Bearer tokens, switching to API keys is a one-line change — replace the `Authorization` header with `X-API-Key`:

<CodeGroup>
  ```python Python theme={null}
  # Before (deprecated)
  headers = {"Authorization": f"Bearer {JWT_TOKEN}"}

  # After (recommended)
  headers = {"X-API-Key": API_KEY}
  ```

  ```javascript JavaScript theme={null}
  // Before (deprecated)
  const headers = { "Authorization": `Bearer ${JWT_TOKEN}` };

  // After (recommended)
  const headers = { "X-API-Key": API_KEY };
  ```
</CodeGroup>

No other changes are needed — all API endpoints accept both authentication methods.