API Keys and Users

hlquery exposes admin-only endpoints for scoped API keys and user accounts.

API keys are intended for application access. Users are named admin/user identities stored by the user auth manager.

Authentication accepts either header:

curl -H "X-API-Key: your-token" http://localhost:9200/collections

curl -H "Authorization: Bearer your-token" http://localhost:9200/collections

Key Concepts

• Granular Actions: Define exactly what a key can do (e.g., only search, or only import documents).
• Collection Scoping: Restrict a key to one or more specific collections.
• Embedded Filters: Automatically inject filters into all search requests made with a specific key.
• Rate Limiting: Limit how many requests a key can make per minute.
• hanalyzer access: Allow or deny access from the bundled web interface with allow_hanalyzer.

---

Action Flags

The following action flags are supported:

Action	Description
search	Allow searching documents and retrieving facet counts.
create	Allow adding new documents.
update	Allow updating existing documents.
delete	Allow deleting documents.
import	Allow bulk importing documents.
collections_list	Allow listing collections.
collections_create	Allow creating new collections.
collections_delete	Allow deleting collections.
* or all	Full access to all operations.

---

Managing API Keys

Only administrators (using the master admin token) can manage API keys via the /keys endpoints.

Create an API Key

Create a new scoped API key.

Endpoint: POST /keys

Body Parameters:

Parameter	Type	Required	Description
description	string	No	A human-readable description of the key.
scopes	object	No	Mapping of collection names to scope objects (see below).
collections	array<string>	No	Legacy: List of collections. Combined with actions.
actions	array<string>	No	Legacy: List of allowed actions.
embedded_filters	string	No	Legacy: Global filters.
rate_limit_per_minute	integer	No	Maximum requests per minute (0 for unlimited).
allow_hanalyzer	boolean	No	Whether this key can be used by hanalyzer.

Scope Object:

Field	Type	Description
actions	array<string>	Actions allowed for this specific collection.
embedded_filters	string	Filters applied only to this collection.

Example Request (Granular Scopes):

curl -X POST http://localhost:9200/keys \
     -H "X-API-Key: admin-token" \
     -d '{
       "description": "Multi-tenant Key",
       "allow_hanalyzer": true,
       "scopes": {
         "public_logs": {
           "actions": ["search"],
           "embedded_filters": "status:=public"
         },
         "user_data": {
           "actions": ["search", "create", "update"],
           "embedded_filters": "user_id:=123"
         }
       }
     }'

Legacy Example Request (Flat Scoping):

curl -X POST http://localhost:9200/keys \
     -H "X-API-Key: admin-token" \
     -d '{
       "description": "Public Search Key",
       "collections": ["products"],
       "actions": ["search"],
       "embedded_filters": "is_public:=true"
     }'

Example Response:

{
  "key": "xyz123...",
  "id": "f25cf3c7..."
}

Note: The full key is only returned once upon creation. Store it securely.

---

List All Keys

Retrieve a list of all active API keys.

Endpoint: GET /keys

Example Request:

curl http://localhost:9200/keys -H "X-API-Key: admin-token"

---

Get a Specific Key

Retrieve metadata for a specific key by its ID.

Endpoint: GET /keys/{id}

---

Update a Key

Update the flags or description of an existing key.

Endpoint: PUT /keys/{id}

Example Request:

curl -X PUT http://localhost:9200/keys/f25cf3c7... \
     -H "X-API-Key: admin-token" \
     -d '{
       "description": "Public write key",
       "rate_limit_per_minute": 120,
       "allow_hanalyzer": false,
       "scopes": {
         "products": {
           "actions": ["search", "create"]
         }
       }
     }'

---

Delete a Key

Revoke an API key immediately.

Endpoint: DELETE /keys/{id}

---

Embedded Filters (Scoped Search)

Embedded filters are a powerful security feature. When a key is created with embedded_filters, hlquery automatically appends these filters to every search request made with that key.

Example Use Case: You want to give a user a key that only allows them to see their own data.

1. Create a key with embedded_filters: "user_id:=55".
2. The user makes a simple search: /collections/data/documents/search?q=*.
3. hlquery internally executes: /collections/data/documents/search?q=*&filter_by=user_id:=55.

The user cannot bypass this filter because it is enforced at the server level based on the API key.

---

CLI Management

The hlquery-cli tool provides convenient commands for key management:

# List all keys
hlquery-cli keys list

# Create a new search-only key
hlquery-cli keys create --desc="Web Search" --cols=products --actions=search

# Create a key with embedded filters
hlquery-cli keys create --desc="User Scoped" --cols=orders --actions=search --embedded-filters="user_id:=123"

# Update a key
hlquery-cli keys update <id> --actions=search,create

# Delete a key
hlquery-cli keys delete <id>

User Management

Users are managed through /users. These endpoints are admin-only.

Method	Endpoint	Purpose
GET	/users	List users
POST	/users	Create user
GET	/users/{name}	Get user metadata
PUT	/users/{name}	Update user flags, description, or token
DELETE	/users/{name}	Delete user

List Users

curl -H "X-API-Key: admin-token" http://localhost:9200/users

Responses include masked tokens only:

{
  "auth_enabled": true,
  "count": 1,
  "users": [
    {
      "name": "admin",
      "description": "Administrator",
      "flags": ["admin", "user"],
      "token_present": true,
      "token_masked": "********abcd"
    }
  ]
}

Create User

If token is omitted, hlquery generates one and returns it once.

curl -X POST http://localhost:9200/users \
  -H "X-API-Key: admin-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "analyst",
    "flags": ["user"],
    "description": "Read-only analyst"
  }'

Flags can be user or admin. The admin flag also grants user.

Update User

curl -X PUT http://localhost:9200/users/analyst \
  -H "X-API-Key: admin-token" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Search analyst",
    "flags": ["user"]
  }'

User names cannot be changed through update.

Delete User

curl -X DELETE http://localhost:9200/users/analyst \
  -H "X-API-Key: admin-token"