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

1. Open the Admin panel

   Log in to Hadiq.io and navigate to Admin in the left sidebar.

2. Go to API Keys

   Select API Keys from the admin menu.

3. 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.

4. 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-.

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.

Use the key in requests

Pass the key in the Authorization header of every request:

Authorization: Bearer <your-api-key>

curl

curl -X GET https://cloud.hadiq.io/api/chat/get-user-chat-sessions \
  -H "Authorization: Bearer onyxk-..."

Manage existing keys

List all API keys

GET /api/admin/api-key

Requires admin role. Returns an array of ApiKeyDescriptor objects.

api_key_id · integer

Unique identifier for the key.

api_key_display · string

Masked version of the key safe to display in a UI (e.g. onyxk-abc...xyz).

api_key · string

The full key value. Only present in the response immediately after creation or regeneration.

api_key_name · string

Human-readable label you assigned to the key.

api_key_role · string

Role assigned to the key: basic or admin.

user_id · string (UUID)

Internal user ID associated with the key.

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:

name · string

New human-readable name for the key.

role · string

New role: basic or admin.

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).