# AI Lakera Guard Configuration

The `ai-lakera-guard` plugin screens AI traffic through the Lakera Guard API to detect prompt injection and other unsafe content in requests and LLM responses.<!-- --> <!-- -->Configuration covers plugin parameters.

## Parameters[​](#parameters "Direct link to Parameters")

See plugin [common configurations](https://docs.api7.ai/apisix/reference/plugin-common-configurations.md) for configuration options available to all plugins.

This plugin supports gateway references in string-valued configuration fields. Use the `$env://` prefix for environment variables or the `$secret://` prefix for values from a secret manager, such as HashiCorp Vault’s [KV secrets engine](https://developer.hashicorp.com/vault/docs/secrets/kv). The gateway resolves these references at runtime. ADC `${NAME}` interpolation is different because ADC resolves it while loading the configuration file, before synchronization. For more information, see [environment variables in plugin](https://docs.api7.ai/apisix/reference/environment-variables.md#plugins) and [secrets](https://docs.api7.ai/apisix/key-concepts/secrets.md).

* api\_key

  string

  required

  valid value:

  non-empty

  ***

  API key used to authenticate to the Lakera Guard API. It is sent as a Bearer token in the `Authorization` header. The value is encrypted before being stored.

* lakera\_endpoint

  string

  default: `https://api.lakera.ai/v2/guard`

  ***

  URL of the Lakera Guard v2 endpoint. Set this to point at a self-hosted or regional Lakera Guard deployment.

* project\_id

  string

  ***

  Lakera project ID whose policy (detectors and thresholds) should be applied to the scan.

* direction

  string

  default: `input`

  valid value:

  `input`, `output`, or `both`

  ***

  Which traffic to scan. With `input`, only the request prompt is scanned. With `output`, only the LLM response is scanned, including streaming responses. With `both`, both are scanned.

* action

  string

  default: `block`

  valid value:

  `block` or `alert`

  ***

  How to handle a flagged verdict. With `block`, the request or response is denied. With `alert`, the traffic is passed through and the verdict is only logged, which is useful for evaluating a policy before enforcing it.

* deny\_code

  integer

  default: `200`

  valid value:

  between 200 and 599 inclusive

  ***

  HTTP status code returned when blocking flagged traffic. The default `200` returns a provider-compatible completion whose content is the failure message, so SDK clients handle it gracefully. Set a `4xx` value to surface the block as an HTTP error instead.

* request\_failure\_message

  string

  default: `Request blocked by Lakera Guard`

  ***

  Message returned in the deny response when the request prompt is flagged.

* response\_failure\_message

  string

  default: `Response blocked by Lakera Guard`

  ***

  Message returned in the deny response when the LLM response is flagged.

* reveal\_failure\_categories

  boolean

  default: `false`

  ***

  If true, append the flagged detector categories (and their confidence levels) to the failure message.

* fail\_open

  boolean

  default: `false`

  ***

  Behavior when the call to the Lakera Guard API fails or times out. If false, the traffic is blocked (fail closed). If true, the traffic is allowed (fail open).

* fail\_mode

  string

  default: `skip`

  valid value:

  `skip`, `warn`, or `error`

  ***

  Behavior when the request format is not recognized as AI traffic, for example when the route does not also configure `ai-proxy` or `ai-proxy-multi`. With `skip`, the request passes unchecked. With `warn`, it passes unchecked and a warning is logged. With `error`, the request is rejected with HTTP 500. None of these outcomes means a Lakera scan succeeded.

* timeout

  integer

  default: `5000`

  valid value:

  greater than or equal to 1

  ***

  Timeout in milliseconds for the request to the Lakera Guard API.

* ssl\_verify

  boolean

  default: `true`

  ***

  If true, verify the TLS certificate of the Lakera Guard endpoint.
