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

# Authentication

> How to create an Hadiq.io API key and use it to authenticate requests.

Hadiq.io uses API keys for authentication. Each key is associated with a role that determines what actions it can perform.

## Create an API key

<Steps>
  <Step title="Open the Admin panel">
    Log in to Hadiq.io and navigate to **Admin** in the left sidebar.
  </Step>

  <Step title="Go to API Keys">
    Select **API Keys** from the admin menu.
  </Step>

  <Step title="Create a new key">
    Click **New API Key**. Give the key a name (optional) and select a role:

    | Role    | Permissions                                                     |
    | ------- | --------------------------------------------------------------- |
    | `basic` | Send chat messages, search, read sessions                       |
    | `admin` | Full access including connectors, ingestion, and key management |

    Click **Create**.
  </Step>

  <Step title="Copy the key">
    The full API key is shown **only once** immediately after creation. Copy it and store it securely. Hadiq.io only stores a hashed representation and cannot show you the key again.

    The key is prefixed with `hadiqk-`.
  </Step>
</Steps>

<Warning>
  Treat your API key like a password. Do not commit it to source control or share it in plaintext. If a key is compromised, delete it and create a new one.
</Warning>

## Use the key in requests

Pass the key in the `Authorization` header of every request:

```
Authorization: Bearer <your-api-key>
```

<CodeGroup>
  ```bash curl theme={null}
  curl -X GET https://cloud.hadiq.io/api/chat/get-user-chat-sessions \
    -H "Authorization: Bearer onyxk-..."
  ```

  ```python Python theme={null}
  import requests

  resp = requests.get(
      "https://cloud.hadiq.io/api/chat/get-user-chat-sessions",
      headers={"Authorization": "Bearer onyxk-..."},
  )
  print(resp.json())
  ```
</CodeGroup>

## Manage existing keys

### List all API keys

```
GET /api/admin/api-key
```

Requires admin role. Returns an array of `ApiKeyDescriptor` objects.

<ResponseField name="api_key_id" type="integer">
  Unique identifier for the key.
</ResponseField>

<ResponseField name="api_key_display" type="string">
  Masked version of the key safe to display in a UI (e.g. `onyxk-abc...xyz`).
</ResponseField>

<ResponseField name="api_key" type="string">
  The full key value. Only present in the response immediately after creation or regeneration.
</ResponseField>

<ResponseField name="api_key_name" type="string">
  Human-readable label you assigned to the key.
</ResponseField>

<ResponseField name="api_key_role" type="string">
  Role assigned to the key: `basic` or `admin`.
</ResponseField>

<ResponseField name="user_id" type="string (UUID)">
  Internal user ID associated with the key.
</ResponseField>

### Regenerate a key

```
POST /api/admin/api-key/{api_key_id}/regenerate
```

Issues a new key value for the given key ID. The old value is immediately invalidated. Returns the same `ApiKeyDescriptor` shape with the new `api_key` included.

### Update a key's name or role

```
PATCH /api/admin/api-key/{api_key_id}
```

Request body:

<ParamField body="name" type="string">
  New human-readable name for the key.
</ParamField>

<ParamField body="role" type="string">
  New role: `basic` or `admin`.
</ParamField>

### Delete a key

```
DELETE /api/admin/api-key/{api_key_id}
```

Returns `204 No Content`. The key is revoked immediately.

## Error codes

| Status             | Cause                                                                                                                               |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| `401 Unauthorized` | The `Authorization` header is missing or the key does not exist.                                                                    |
| `403 Forbidden`    | The key exists but does not have permission to perform the requested action (for example, a `basic` key calling an admin endpoint). |