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

# Create API Key

> Create a new API key for programmatic access to your tenant

## Create API Key

```text theme={"dark"}
POST /v1/api-keys
```

Creates a new API key. The full key value is returned **only once** in the response -- store it securely.

### Request Body

| Field                   | Type    | Required | Description                                                   |
| ----------------------- | ------- | -------- | ------------------------------------------------------------- |
| `name`                  | string  | Yes      | A descriptive name (e.g., "CI/CD Pipeline", "Backend Server") |
| `rate_limit_requests`   | integer | No       | Maximum requests per window for this key                      |
| `rate_limit_window_sec` | integer | No       | Rate limit window duration in seconds                         |

<Note>
  The `key_type` is set automatically based on the host the request is sent to and **cannot** be specified in the request body. Requests to `api.knoxcall.com` produce a `standard` key; requests to `sandbox.knoxcall.com` produce a `test` key.
</Note>

### Response

```json theme={"dark"}
{
  "data": {
    "key_id": "tk_9f3a1c2e",
    "api_key": "tk_9f3a1c2e_4d2b8a1f0c9e7d6b5a4c3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e1",
    "key_prefix": "tk_9f3a1c2e_",
    "key_type": "standard",
    "name": "CI/CD Pipeline",
    "message": "Store this API key securely. It will not be shown again."
  },
  "meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000" }
}
```

<Warning>
  The `api_key` field contains the full key and is **only returned at creation time**. KnoxCall does not store the plain-text key. If you lose it, you must revoke it and create a new one.
</Warning>

<CodeGroup>
  ```bash cURL theme={"dark"}
  curl -X POST https://api.knoxcall.com/v1/api-keys \
    -H "Authorization: Bearer tk_live_abc123..." \
    -H "Content-Type: application/json" \
    -d '{
      "name": "CI/CD Pipeline"
    }'
  ```

  ```python Python theme={"dark"}
  import requests

  resp = requests.post(
      "https://api.knoxcall.com/v1/api-keys",
      headers={
          "Authorization": "Bearer tk_live_abc123...",
          "Content-Type": "application/json"
      },
      json={"name": "CI/CD Pipeline"}
  )
  new_key = resp.json()["data"]
  print(f"Store this key: {new_key['api_key']}")
  ```

  ```javascript Node.js theme={"dark"}
  const resp = await fetch("https://api.knoxcall.com/v1/api-keys", {
    method: "POST",
    headers: {
      Authorization: "Bearer tk_live_abc123...",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ name: "CI/CD Pipeline" })
  });
  const { data: newKey } = await resp.json();
  console.log(`Store this key: ${newKey.api_key}`);
  ```
</CodeGroup>

### Errors

| Status | Type               | Description          |
| ------ | ------------------ | -------------------- |
| 400    | `validation_error` | Missing `name` field |