> For the complete documentation index, see [llms.txt](https://docs.digitalapi.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digitalapi.ai/api-gateway/plugin-reference/plugins-helix.md).
# Helix plugins
Plugins in this category are AILIX-specific extensions: developer-portal hooks, request-ID propagation, plugin-schema introspection, internal control-plane integrations. They are pre-attached on every gateway and rarely need direct configuration. The catalogue ships 11 Helix plugins.
{% hint style="info" %}
**In this category:** [`helix.api-product-enforcer`](#helix.api-product-enforcer), [`helix.client-credentials-token`](#helix.client-credentials-token), [`helix.helix-analytics`](#helix.helix-analytics), [`helix.json-to-xml`](#helix.json-to-xml), [`helix.jsonp-wrapper`](#helix.jsonp-wrapper), [`helix.kvm-fetcher`](#helix.kvm-fetcher), [`helix.log-data-mask`](#helix.log-data-mask), [`helix.lua-callout`](#helix.lua-callout), [`helix.request-chain`](#helix.request-chain), [`helix.service-callout`](#helix.service-callout), [`helix.xml-to-json`](#helix.xml-to-json)
{% endhint %}
### `helix.api-product-enforcer`
The `helix.api-product-enforcer` plugin is part of the Helix API Products model. It runs in the **access** phase **after** authentication has attached a **consumer** (for example helix.client-credentials-token in validate mode, or `key-auth`). It uses `ctx.consumer` set by the auth plugin.
{% hint style="info" %}
**Priority** `2399` · **Category** Helix
{% endhint %}
Configuration and details
### What it does
1. Reads `ctx.consumer.credential_products`: a map of product id to rank (lower rank = evaluated first).
2. For each product id, loads the document from the `/products` the gateway configuration store prefix (same data as the Admin products API).
3. **Authorizes** the request: the route defines `service_id`, and at least one subscribed product’s `service_ids` includes that `service_id`.
4. **Enforces quota** in **rank order** on matching products (see **Sequential quota** below), capped by `plugin_attr.max_products_for_quota` (default **3**) to the first n matches by rank. At most **one** product’s counter consumes the request (or `quota.limit == -1` for unlimited). Each touched product may set `ctx["helix_" .. product_id .. "_remaining"]` (see below).
5. Sets `X-Consumer-App-Id` / `X-Consumer-Developer-Id` on the request toward the upstream.
### `helix.client-credentials-token`
The `helix.client-credentials-token` Plugin is a dual-mode OAuth2 Client Credentials plugin that handles both JWT **generation** and **validation** in a single plugin, eliminating the need for a separate `jwt-auth` plugin.
{% hint style="info" %}
**Priority** `2450` · **Category** Helix
{% endhint %}
Configuration and details
**Generate mode** (`mode: "generate"`): Used on token endpoints (e.g. `/oauth/token`). The client sends `Authorization: Basic base64(client_id:client_secret)`. The plugin resolves the Consumer credential, verifies the secret, signs a JWT, and stores it in `ctx.access_token` for a downstream plugin to return as the HTTP response.
**Validate mode** (`mode: "validate"`): Used on protected API routes. The client sends `Authorization: Bearer ` (or an API key when `validate_auth_type` is `key-auth`). The plugin verifies credentials, resolves the credential, and calls **`attach_consumer`**, which sets **`ctx.consumer`** (including **`credential_products`**). Downstream plugins such as **`helix.api-product-enforcer`** load product definitions from **`/products`** in the gateway configuration store.
| Name | Type | Required | Default | Description |
| -------------------- | ------- | ----------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| mode | string | False | `"validate"` | Plugin mode: `"generate"` for token issuance, `"validate"` for JWT verification. |
| validate\_auth\_type | string | False | `"jwt-auth"` | Validate mode only: `"jwt-auth"` (Bearer JWT) or `"key-auth"` (API key header). |
| apikey\_header | string | False | `"apikey"` | Header name for the client id when `validate_auth_type` is `key-auth`. |
| signing\_secret | string | Conditional | | Shared secret for HS256 signing (generate) and JWT verification (validate with `jwt-auth`). Required for validate mode when `validate_auth_type` is `jwt-auth`. Must match between generate and validate routes that use JWTs. |
| client\_id\_claim | string | False | `"key"` | JWT payload field that stores the client\_id. |
| token\_ttl | integer | False | `3600` | Token lifetime in seconds (JWT `exp` = `iat` + token\_ttl). Minimum 1. Used in generate mode only. |
| payload | object | False | | Additional claims to include in the JWT payload. Merged with the client\_id claim, `iat`, and `exp`. Used in generate mode only. |
| algorithm | string | False | `"HS256"` | Signing algorithm: `"HS256"` or `"RS256"`. |
| private\_key | string | Conditional | | PEM private key for RS256 signing. Required when `algorithm` is `"RS256"`. |
| base64\_secret | boolean | False | `false` | When true, `signing_secret` is base64-decoded before use. |
| base64\_private\_key | boolean | False | `false` | When true, `private_key` is base64-decoded before use. |
| Name | Type | Required | Description |
| ------ | ------ | -------- | ------------------------------------------------------------------------------------------------ |
| key | string | True | The client\_id. Used as the lookup key when resolving credentials from Basic auth or JWT claims. |
| secret | string | True | The client\_secret. Verified during generate mode (Basic auth). |
### `helix.helix-analytics`
The `helix.helix-analytics` plugin runs in the `log` phase and writes one JSON line per request to a file.
{% hint style="info" %}
**Priority** `50` · **Category** Helix
{% endhint %}
Configuration and details
The plugin configuration schema is empty (`{}`), so route- or service-level options are not supported. Enable it where needed; it derives fields from request context (`ctx`, `ctx.var`, matched route, and consumer). Product fields are populated when `helix.api-product-enforcer` (or other logic) sets `ctx.helix_product_id` and `ctx.helix_product_name`.
| Name | Type | Default | Description |
| ---- | ------ | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| path | string | `/var/log/ailix/helix-analytics.log` | Log destination. If `path` is `/var/log/ailix`, an existing directory, or ends with `/`, logs are written to `/helix-analytics.log`. Otherwise the value is treated as a file path. |
| Field | Description |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| id | Request ID (for example `ctx.var.request_id`). |
| api\_id | Service ID (`ctx.service_id`). |
| api\_name | Service name (`ctx.service_name`). |
| org\_id | Organization ID from `service.labels.org_id`; `null` if unset. |
| env\_id | Environment ID from `service.labels.env_id`; `null` if unset. |
| env\_name | Environment name from `service.labels.env_name`; `null` if unset. |
| route\_id | Route ID. |
| route\_name | Route name (`ctx.route_name`) when set. |
| upstream\_id | Upstream ID from context or the matched route. |
| timestamp | ISO 8601 time derived from the request start time. |
| request\_method | HTTP method. |
| response\_status\_code | HTTP response status. |
| api\_path | Request URI path. |
| total\_response\_time | Total request time in milliseconds. |
| upstream\_path | Upstream URI (`ctx.var.upstream_uri`). |
| upstream\_response\_time | Upstream time in milliseconds. |
| request\_size | Request size in bytes. |
| response\_size | Response size in bytes. |
| consumer\_name | Consumer username (`ctx.consumer.username`) when set. |
| app\_id | `ctx.consumer.credential_id` when the consumer is a Helix credential; otherwise `null`. |
| app\_name | `ctx.consumer.credential_name` when set; if only `credential_id` is present, same as `app_id`; otherwise `null`. |
| product\_id | Matched product id (`ctx.helix_product_id`) from the enforcer; `null` if unset. |
| product\_name | Matched product name (`ctx.helix_product_name`); `null` if unset. |
| custom\_analytics | `ctx.var.helix_custom_analytics` if another plugin set it. |
| tokens\_used | `ctx.var.helix_tokens_used` when set (for example usage tracking). |
| client\_ip | Client IP (respects trusted proxy configuration). |
| revision\_id | `labels.revision_id` from the merged route, or from the service when the route has no label. |
### `helix.json-to-xml`
The `helix.json-to-xml` Plugin dynamically converts upstream JSON responses to XML when the client includes `application/xml` in the request `Accept` header. The transformation is schema-free and template-free, JSON object keys map directly to XML element names.
{% hint style="info" %}
**Priority** `998` · **Category** Helix
{% endhint %}
Configuration and details
When XML is not requested, the plugin is a no-op and the original JSON response is preserved unchanged. The plugin also safely passes through the original response when:
* The upstream `Content-Type` does not match the configured allow-list.
* The upstream response is compressed (`Content-Encoding` header is present).
* The response body exceeds the configured `max_body_size`.
* The response body is not valid JSON.
| Name | Type | Required | Default | Description |
| ----------------- | ---------------- | -------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| root\_name | string | False | response | Name of the root XML element that wraps the entire response. |
| array\_item\_name | string | False | item | Tag name used for each child element when serializing JSON arrays. |
| max\_body\_size | integer | False | 1048576 (1 MB) | Maximum response body size in bytes eligible for transformation. Bodies exceeding this limit are passed through unchanged. |
| pretty | boolean | False | false | When true, the XML output is pretty-printed with 2-space indentation and newlines. |
| enable\_decl | boolean | False | true | When true, prepends `` to the output. |
| content\_types | array of strings | False | \["application/json"] | List of upstream Content-Type values eligible for conversion. Parameters like `; charset=utf-8` are stripped before matching. |
### `helix.jsonp-wrapper`
The `helix.jsonp-wrapper` Plugin is part of the Helix ecosystem for AILIX. It wraps a JSON response body as JSONP when the request includes a callback query argument (by default `callback`). The final payload is emitted as `callback();` and the response `Content-Type` is set for JavaScript.
{% hint style="info" %}
**Priority** `850` · **Category** Helix
{% endhint %}
Configuration and details
If the request has no callback parameter, or the HTTP method is listed in `skip_methods` (default: `OPTIONS`), the plugin does nothing and the upstream response is unchanged.
| Name | Type | Required | Default | Description |
| ------------------------- | ---------------- | -------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| callback\_arg | string | False | `callback` | Query parameter that carries the JSONP function name. |
| validate\_callback | boolean | False | `true` | When `true`, the callback is matched with `callback_pattern` using the `jo` PCRE options (JIT + DUPNAMES as supported). |
| callback\_pattern | string | False | `^[A-Za-z_$][0-9A-Za-z_$\.]*$` | Regex the callback name must match when `validate_callback` is `true`. |
| reject\_invalid\_callback | boolean | False | `true` | When `validate_callback` is `true` and the name does not match, return `400` with a JSON error if `true`, or log a warning and skip JSONP (pass through JSON) if `false`. |
| content\_type | string | False | `application/javascript; charset=utf-8` | Response `Content-Type` when JSONP wrapping is applied. |
| append\_semicolon | boolean | False | `true` | When `true`, append `;` after the closing `)` of the JSONP call. |
| skip\_methods | array of strings | False | `["OPTIONS"]` | Methods for which the plugin is skipped even if a callback is present. |
| strip\_callback\_arg | boolean | False | `true` | When `true`, remove `callback_arg` from the query string before the request is sent upstream. |
| extra\_strip\_args | array of strings | False | - | Additional query parameter names to remove for upstream. |
### `helix.kvm-fetcher`
The `kvm-fetcher` Plugin is part of the Helix ecosystem for AILIX. It securely fetches encrypted key-value pairs from Redis, decrypts them using Vault-managed keys, and exposes them in the AILIX context (`ctx.kvm`) for downstream plugins or upstreams.
{% hint style="info" %}
**Priority** `3001` · **Category** Helix · **Required** `keys`
{% endhint %}
### `helix.log-data-mask`
The `helix.log-data-mask` Plugin defines rules to mask or remove sensitive data from request and response data before they are written to access logs. The plugin runs in the log phase and stores its configuration in `ctx.helix.data_mask_config`. When AILIX generates log entries (for example via the file-logger or other logging plugins), the masking rules are applied so that query parameters, headers, or body fields are either removed, replaced with a fixed value, or transformed by a regex substitution.
{% hint style="info" %}
**Priority** `999` · **Category** Helix
{% endhint %}
Configuration and details
You can configure separate rule sets for request and response. Each rule targets a specific field by name and type (query, header, or body) and applies one of the actions: remove, replace, or regex.
| Name | Type | Required | Description |
| -------- | ----- | -------- | ----------------------------------------------------------------------------------------------- |
| request | array | No\* | List of masking rules applied to request data (query, headers, body) when building log entries. |
| response | array | No\* | List of masking rules applied to response data when building log entries. |
| Name | Type | Required | Description |
| ------------ | ------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------- |
| action | string | True | One of: `remove` (drop the value from logs), `replace` (replace with a fixed string), `regex` (substitute using a regex pattern). |
| name | string | True | Name of the query parameter, header, or body field to mask (case-insensitive for headers). |
| type | string | True | Where the field lives: `query`, `header`, or `body`. |
| value | string | Conditional | For `replace`: replacement string (min length 1). For `regex`: replacement string (required but may be empty). |
| regex | string | Conditional | For `regex` action only: PCRE pattern used for substitution. Required when `action` is `regex`. |
| body\_format | string | False | When `type` is `body`: `json` or `urlencoded`. Used to parse and locate the body field. |
### `helix.lua-callout`
The `helix.lua-callout` Plugin executes **user-provided Lua code** on a route or service. Each entry in `functions` is a string that is loaded with `loadstring`, evaluated once to obtain a **function**, then invoked as `func(conf, ctx)` in the configured **phase**. Functions run in order; if any function returns a non-nil **HTTP status code** and/or **body**, the pipeline **short-circuits** and that response is returned to the client (same pattern as returning from a plugin phase handler).
{% hint style="info" %}
**Priority** `0` · **Category** Helix · **Required** `functions`
{% endhint %}
Configuration and details
Supported phases: `rewrite`, `access`, `header_filter`, `body_filter`, `log`, `before_proxy`. Only the phase named in `phase` runs your functions; the plugin registers handlers for all phases but no-ops except for the selected one.
:::caution
This plugin executes arbitrary Lua stored in configuration. Restrict Admin API access and audit who can create or change routes using `helix.lua-callout`. Misuse can compromise the gateway or leak data.
:::
| Name | Type | Required | Default | Description |
| ------------- | ------ | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| phase | string | False | `access` | Phase in which to run the functions: `rewrite`, `access`, `header_filter`, `body_filter`, `log`, `before_proxy`. |
| functions | array | True | | Non-empty list of Lua source strings. Each string must compile and, when executed, return a **function** with signature `function(conf, ctx)`. Return `code, body` to stop processing and respond with that status and body (`body` may be a table for JSON). Return nothing (or `nil, nil`) to continue. |
| error\_policy | string | False | `open` | `open`: if a step fails to load at runtime or raises inside `pcall`, log the error and continue to the next function (failed loads leave that slot empty). `close`: on load failure or runtime error in a step, respond with **503** and a JSON body (see below). Runtime details are **not** included in the client response; they are logged only. |
### `helix.request-chain`
The `helix.request-chain` Plugin runs an ordered list of steps in the **access** phase.
{% hint style="info" %}
**Priority** `1005` · **Category** Helix · **Required** `steps`
{% endhint %}
Configuration and details
Each step:
* points to a loaded HTTP plugin by name (`plugin`),
* provides that plugin configuration (`conf`),
* can optionally define step-level `_meta.filter` (vars expression).
Steps run in array order. If a step returns `code` or `body`, the chain short-circuits:
* for non-error codes, the chain immediately returns that result;
* for HTTP errors (`code >= 400`), behavior depends on `error_policy`.
Step plugins are not hardcoded to a fixed Helix-only list. At schema check time, the plugin allows loaded HTTP plugins that expose an `access` handler.
| Name | Type | Required | Default | Description |
| ------------- | ------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| steps | array | True | | Ordered list of steps (1-50). |
| error\_policy | string | False | `close` | `close`: stop on step Lua error / step plugin missing / step plugin has no `access` / step HTTP error (`code >= 400`). `open`: log and continue to next step. |
| error\_status | integer | False | `503` | Status used for synthesized chain failures in `close` mode (Lua error, plugin missing, plugin has no `access`). Range: `400-599`. |
| Name | Type | Required | Description |
| ------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------- |
| plugin | string | True | Loaded HTTP plugin name that provides an `access` handler. |
| conf | object | True | Plugin configuration for that step. Must pass the target plugin’s `check_schema`. |
| \_meta.filter | array | False | Optional lua-resty-expr vars expression. Evaluated against `ctx.var` before this step runs. If false, the step is skipped. |
### `helix.service-callout`
The `helix.service-callout` Plugin performs independent outbound HTTP calls to external services via a direct URI. The response is stored in `ctx.helix.` so that downstream plugins can consume it. The plugin supports the rewrite and access phases and can run callouts either synchronously (default) or asynchronously (fire-and-forget).
{% hint style="info" %}
**Priority** `2003` · **Category** Helix · **Required** `uri`, `phase`
{% endhint %}
Configuration and details
When running synchronously, the callout blocks until the external service responds. The response status, body, and headers (or selected parts) are mapped into the request context under a configurable namespace. When running asynchronously, the callout is scheduled in the background and the request continues immediately; no response is stored in context.
| Name | Type | Required | Default | Description |
| ---------------------- | ------- | -------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| uri | string | True | | Full URI for the outbound HTTP call (must be HTTPS in production). |
| phase | string | True | | Phase in which to run the callout: `rewrite` or `access`. |
| method | string | False | GET | HTTP method: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, or `OPTIONS`. |
| async | boolean | False | false | When true, execute the callout asynchronously (fire-and-forget). When false, execute synchronously and store the response in context. |
| headers | object | False | | Custom headers to send. Values support variable substitution. |
| timeout | integer | False | 3000 | Request timeout in milliseconds (1–60000). |
| ssl\_verify | boolean | False | true | Whether to verify the TLS certificate of the external service. |
| keepalive | boolean | False | true | Whether to use connection keepalive. |
| keepalive\_timeout | integer | False | 60000 | Keepalive timeout in milliseconds (minimum 1000). |
| keepalive\_pool | integer | False | 5 | Size of the keepalive connection pool (minimum 1). |
| error\_policy | string | False | fail-open | Behavior when the callout fails: `fail-open` (continue, store error in context), `fail-close` (return 503), or `log-only` (log and continue). |
| fail\_close\_message | string | False | | Custom error message returned when `error_policy` is `fail-close`. |
| request\_body | string | False | | Custom request body with variable substitution (e.g. `{"email": "${ctx.var.email}"}`). If set, overrides `send_request_object`. |
| send\_request\_object | boolean | False | false | When true, send a JSON body containing the current request (method, URI, headers, body, query). |
| request\_headers | array | False | \[] | List of client request header names to forward to the external service. |
| map\_response\_to\_ctx | object | False | `{"external_status":"status","external_body":"body"}` | Maps response fields to context keys. Keys are context field names; values are response paths: `status`, `body`, `body.` (nested JSON field, e.g. `body.access_token` or `body.data.token`), `headers`, or `headers.`. When a `body.` path is used the body is JSON-decoded automatically. |
| ctx\_namespace | string | False | service\_callout | Namespace under `ctx.helix` where the mapped response (or error info) is stored. |
### `helix.xml-to-json`
The `helix.xml-to-json` Plugin dynamically converts upstream XML responses to JSON when the client includes `application/json` in the request `Accept` header. The transformation is schema-free and template-free, XML element names map directly to JSON keys, attributes are exposed under `@attributes`, and text content under `#text`.
{% hint style="info" %}
**Priority** `997` · **Category** Helix
{% endhint %}
Configuration and details
When JSON is not requested, the plugin is a no-op and the original XML response is preserved unchanged. The plugin also safely passes through the original response when:
* The upstream `Content-Type` does not match the configured allow-list.
* The upstream response is compressed (`Content-Encoding` header is present).
* The response body exceeds the configured `max_body_size`.
* The response body is not well-formed XML.
| Name | Type | Required | Default | Description |
| --------------- | ---------------- | -------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| root\_name | string | False | | Optional wrapper key for the JSON output. When set, the parsed document is nested under this key. When omitted, the original XML root element name is preserved as the top-level JSON key. |
| max\_body\_size | integer | False | 1048576 (1 MB) | Maximum response body size in bytes eligible for transformation. Bodies exceeding this limit are passed through unchanged. |
| pretty | boolean | False | false | When true, the JSON output is pretty-printed with indentation and newlines. |
| content\_types | array of strings | False | \["application/xml", "text/xml"] | List of upstream Content-Type values eligible for conversion. Parameters like `; charset=utf-8` are stripped before matching. |
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.digitalapi.ai/api-gateway/plugin-reference/plugins-helix.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.