---
title: "Create a EntitlementEnforcement plugin"
method: POST
path: "/v2/control-planes/{controlPlaneId}/core-entities/plugins#EntitlementEnforcement"
tags: ["Plugins"]
---

# Create a EntitlementEnforcement plugin

`POST /v2/control-planes/{controlPlaneId}/core-entities/plugins#EntitlementEnforcement`

Create a EntitlementEnforcement plugin

## Request body

- EntitlementEnforcementPlugin — A Plugin entity represents a plugin configuration that will be executed during the HTTP request/response lifecycle. It is how you can add functionalities to Services that run behind Kong, like Authentication or Rate Limiting for example. You can find more information about how to install and what values each plugin takes by visiting the [Kong Hub](https://docs.konghq.com/hub/). When adding a Plugin Configuration to a Service, every request made by a client to that Service will run said Plugin. If a Plugin needs to be tuned to different values for some specific Consumers, you can do so by creating a separate plugin instance that specifies both the Service and the Consumer, through the `service` and `consumer` fields.
  - `condition` string, nullable — An expression used for conditional control over plugin execution. If the expression evaluates to `true` during the request flow, the plugin is executed; otherwise, it is skipped.
  - `created_at` integer, nullable — Unix epoch when the resource was created.
  - `enabled` boolean, nullable — Whether the plugin is applied.
  - `id` string, nullable — A string representing a UUID (universally unique identifier).
  - `instance_name` string, nullable — A unique string representing a UTF-8 encoded name.
  - `name` 'entitlement-enforcement', required — The name of the Plugin that's going to be added. Currently, the Plugin must be installed in every Kong instance separately.
  - `ordering` object, nullable
    - `after` object
      - `access` string[]
    - `before` object
      - `access` string[]
  - `partials` object[], nullable — A list of partials to be used by the plugin.
    - `id` string — A string representing a UUID (universally unique identifier).
    - `name` string — A unique string representing a UTF-8 encoded name.
    - `path` string, required
  - `tags` string[], nullable — An optional set of strings associated with the Plugin for grouping and filtering.
  - `updated_at` integer, nullable — Unix epoch when the resource was last updated.
  - `config` object, required
    - `api_token` string, required — Bearer token for authenticating with the entitlement access endpoint.
    - `credit_balance_required` boolean — If set to true, gateway will fetch credit balance for subject.
    - `customer` object — The customer identifies who gets billed for each request. Choose where the plugin should look for the customer identifier.
      - `field` string, nullable — The header name, query parameter, consumer field, or application field that contains the customer identifier, e.g. 'x-customer-id'
      - `look_up_value_in` 'application' | 'consumer' | 'header' | 'query' — Where to find the customer identifier in the request.
    - `deny_unknown_customers` boolean — If set to true, gateway will deny access to any unknown subjects.
    - `entitlement_access_endpoint` string, required — A string representing a URL, such as https://example.com/path/to/resource?q=search.
    - `fail_policy` 'allow' | 'block' — Policy to apply when enforcement state cannot be retrieved.
    - `feature` object, required — The feature identifies what capability is being accessed and enforced.
      - `key` string, required — The feature key
    - `keepalive` number — How long in milliseconds an idle connection to the entitlement access endpoint is kept open before being closed.
    - `l1_cache_ttl_seconds` number — Time in seconds to keep enforcement state in Kong's local L1 cache
    - `l2_cache_ttl_seconds` number — Time in seconds to keep enforcement state in Redis
    - `max_stale_seconds` number — Maximum age in seconds of cached enforcement state before it is considered stale and must be refreshed from Redis
    - `redis` object, nullable
      - `cloud_authentication` object, nullable — Cloud auth related configs for connecting to a Cloud Provider's Redis instance.
        - `auth_provider` 'aws' | 'azure' | 'gcp' | 'oauth' — Auth providers to be used to authenticate to a Cloud Provider's Redis instance.
        - `aws_access_key_id` string, nullable — AWS Access Key ID to be used for authentication when `auth_provider` is set to `aws`.
        - `aws_assume_role_arn` string, nullable — The ARN of the IAM role to assume for generating ElastiCache IAM authentication tokens.
        - `aws_cache_name` string, nullable — The name of the AWS Elasticache cluster when `auth_provider` is set to `aws`.
        - `aws_is_serverless` boolean — This flag specifies whether the cluster is serverless when auth_provider is set to `aws`.
        - `aws_region` string, nullable — The region of the AWS ElastiCache cluster when `auth_provider` is set to `aws`.
        - `aws_role_session_name` string, nullable — The session name for the temporary credentials when assuming the IAM role.
        - `aws_secret_access_key` string, nullable — AWS Secret Access Key to be used for authentication when `auth_provider` is set to `aws`.
        - `azure_client_id` string, nullable — Azure Client ID to be used for authentication when `auth_provider` is set to `azure`.
        - `azure_client_secret` string, nullable — Azure Client Secret to be used for authentication when `auth_provider` is set to `azure`.
        - `azure_tenant_id` string, nullable — Azure Tenant ID to be used for authentication when `auth_provider` is set to `azure`.
        - `gcp_service_account_json` string, nullable — GCP Service Account JSON to be used for authentication when `auth_provider` is set to `gcp`.
        - `oauth` object, nullable — OAuth 2.0 client configuration used to authenticate to Redis when `auth_provider` is set to `oauth`.
          - `auth_method` 'client_secret_basic' | 'client_secret_jwt' | 'client_secret_post' — Client authentication method used against the token endpoint.
          - `client_id` string, nullable — OAuth 2.0 client ID.
          - `client_secret` string, nullable — OAuth 2.0 client secret.
          - `client_secret_jwt_alg` 'HS256' | 'HS512' — Signing algorithm used for `client_secret_jwt` client authentication.
          - `grant_type` 'client_credentials' | 'password' — OAuth 2.0 grant type used to request access tokens.
          - `password` string, nullable — Resource owner password, used with the `password` grant type.
          - `redis_username` string, nullable — Static Redis ACL username sent with `AUTH <username> <token>`.
          - `redis_username_claim` string, nullable — JWT claim in the access token used to derive the Redis ACL username (for example, `oid` for Microsoft Entra ID).
          - `scopes` string[] — OAuth 2.0 scopes to request.
          - `ssl_verify` boolean — Whether to verify the TLS certificate of the token endpoint.
          - `timeout` integer — Timeout, in milliseconds, for requests to the token endpoint.
          - `token_endpoint` string, nullable — OAuth 2.0 token endpoint URL used to request access tokens.
          - `token_headers` object, nullable — Additional HTTP headers to send with the token request.
          - `token_post_args` object, nullable — Additional POST body arguments to send with the token request.
          - `username` string, nullable — Resource owner username, used with the `password` grant type.
      - `cluster_max_redirections` integer — Maximum retry attempts for redirection.
      - `cluster_nodes` object[], nullable — Cluster addresses to use for Redis connections when the `redis` strategy is defined. Defining this field implies using a Redis Cluster. The minimum length of the array is 1 element.
        - `ip` string — A string representing a host name, such as example.com.
        - `port` integer — An integer representing a port number between 0 and 65535, inclusive.
      - `connect_timeout` integer — An integer representing a timeout in milliseconds. Must be between 0 and 2^31-2.
      - `connection_is_proxied` boolean — If the connection to Redis is proxied (e.g. Envoy), set it `true`. Set the `host` and `port` to point to the proxy address.
      - `database` integer — Database to use for the Redis connection when using the `redis` strategy
      - `host` string — A string representing a host name, such as example.com.
      - `keepalive_backlog` integer, nullable — Limits the total number of opened connections for a pool. If the connection pool is full, connection queues above the limit go into the backlog queue. If the backlog queue is full, subsequent connect operations fail and return `nil`. Queued operations (subject to set timeouts) resume once the number of connections in the pool is less than `keepalive_pool_size`. If latency is high or throughput is low, try increasing this value. Empirically, this value is larger than `keepalive_pool_size`.
      - `keepalive_pool_size` integer — The size limit for every cosocket connection pool associated with every remote server, per worker process. If neither `keepalive_pool_size` nor `keepalive_backlog` is specified, no pool is created. If `keepalive_pool_size` isn't specified but `keepalive_backlog` is specified, then the pool uses the default value. Try to increase (e.g. 512) this value if latency is high or throughput is low.
      - `password` string, nullable — Password to use for Redis connections. If undefined, no AUTH commands are sent to Redis.
      - `port` string — An integer representing a port number between 0 and 65535, inclusive.
      - `read_timeout` integer — An integer representing a timeout in milliseconds. Must be between 0 and 2^31-2.
      - `send_timeout` integer — An integer representing a timeout in milliseconds. Must be between 0 and 2^31-2.
      - `sentinel_master` string, nullable — Sentinel master to use for Redis connections. Defining this value implies using Redis Sentinel.
      - `sentinel_nodes` object[], nullable — Sentinel node addresses to use for Redis connections when the `redis` strategy is defined. Defining this field implies using a Redis Sentinel. The minimum length of the array is 1 element.
        - `host` string — A string representing a host name, such as example.com.
        - `port` integer — An integer representing a port number between 0 and 65535, inclusive.
      - `sentinel_password` string, nullable — Sentinel password to authenticate with a Redis Sentinel instance. If undefined, no AUTH commands are sent to Redis Sentinels.
      - `sentinel_role` 'any' | 'master' | 'slave' — Sentinel role to use for Redis connections when the `redis` strategy is defined. Defining this value implies using Redis Sentinel.
      - `sentinel_username` string, nullable — Sentinel username to authenticate with a Redis Sentinel instance. If undefined, ACL authentication won't be performed. This requires Redis v6.2.0+.
      - `server_name` string, nullable — A string representing an SNI (server name indication) value for TLS.
      - `ssl` boolean — If set to true, uses SSL to connect to Redis.
      - `ssl_verify` boolean — If set to true, verifies the validity of the server SSL certificate. If setting this parameter, also configure `lua_ssl_trusted_certificate` in `kong.conf` to specify the CA (or server) certificate used by your Redis server. You may also need to configure `lua_ssl_verify_depth` accordingly.
      - `username` string, nullable — Username to use for Redis connections. If undefined, ACL authentication won't be performed. This requires Redis v6.0.0+. To be compatible with Redis v5.x.y, you can set it to `default`.
    - `refresh_interval` number — How often in seconds to poll enforcement state from the entitlement access endpoint
    - `response_codes` object
      - `CUSTOMER_NOT_FOUND` object
        - `http_status` number — Status code to return when enforcement is triggered.
        - `message` string — Message to return when enforcement is triggered.
      - `FEATURE_NOT_FOUND` object
        - `http_status` number — Status code to return when enforcement is triggered.
        - `message` string — Message to return when enforcement is triggered.
      - `FEATURE_UNAVAILABLE` object
        - `http_status` number — Status code to return when enforcement is triggered.
        - `message` string — Message to return when enforcement is triggered.
      - `NO_CREDIT_AVAILABLE` object
        - `http_status` number — Status code to return when enforcement is triggered.
        - `message` string — Message to return when enforcement is triggered.
      - `USAGE_LIMIT_REACHED` object
        - `http_status` number — Status code to return when enforcement is triggered.
        - `message` string — Message to return when enforcement is triggered.
    - `ssl_verify` boolean — Verify the TLS certificate presented by the entitlement access endpoint.
    - `sync_rate` number — How often in seconds to sync enforcement state from redis
    - `timeout` number — Maximum time in milliseconds to wait for a response from the entitlement access endpoint.
  - `consumer` object, nullable — If set, the plugin will activate only for requests where the specified has been authenticated. (Note that some plugins can not be restricted to consumers this way.). Leave unset for the plugin to activate regardless of the authenticated Consumer.
    - `id` string
  - `protocols` string[] — A set of strings representing HTTP protocols.
  - `route` object, nullable — If set, the plugin will only activate when receiving requests via the specified route. Leave unset for the plugin to activate regardless of the route being used.
    - `id` string
  - `service` object, nullable — If set, the plugin will only activate when receiving requests via one of the routes belonging to the specified Service. Leave unset for the plugin to activate regardless of the Service being matched.
    - `id` string

## Response `201`

Created EntitlementEnforcement plugin

- EntitlementEnforcementPlugin — A Plugin entity represents a plugin configuration that will be executed during the HTTP request/response lifecycle. It is how you can add functionalities to Services that run behind Kong, like Authentication or Rate Limiting for example. You can find more information about how to install and what values each plugin takes by visiting the [Kong Hub](https://docs.konghq.com/hub/). When adding a Plugin Configuration to a Service, every request made by a client to that Service will run said Plugin. If a Plugin needs to be tuned to different values for some specific Consumers, you can do so by creating a separate plugin instance that specifies both the Service and the Consumer, through the `service` and `consumer` fields.
  - `condition` string, nullable — An expression used for conditional control over plugin execution. If the expression evaluates to `true` during the request flow, the plugin is executed; otherwise, it is skipped.
  - `created_at` integer, nullable — Unix epoch when the resource was created.
  - `enabled` boolean, nullable — Whether the plugin is applied.
  - `id` string, nullable — A string representing a UUID (universally unique identifier).
  - `instance_name` string, nullable — A unique string representing a UTF-8 encoded name.
  - `name` 'entitlement-enforcement', required — The name of the Plugin that's going to be added. Currently, the Plugin must be installed in every Kong instance separately.
  - `ordering` object, nullable
    - `after` object
      - `access` string[]
    - `before` object
      - `access` string[]
  - `partials` object[], nullable — A list of partials to be used by the plugin.
    - `id` string — A string representing a UUID (universally unique identifier).
    - `name` string — A unique string representing a UTF-8 encoded name.
    - `path` string, required
  - `tags` string[], nullable — An optional set of strings associated with the Plugin for grouping and filtering.
  - `updated_at` integer, nullable — Unix epoch when the resource was last updated.
  - `config` object, required
    - `api_token` string, required — Bearer token for authenticating with the entitlement access endpoint.
    - `credit_balance_required` boolean — If set to true, gateway will fetch credit balance for subject.
    - `customer` object — The customer identifies who gets billed for each request. Choose where the plugin should look for the customer identifier.
      - `field` string, nullable — The header name, query parameter, consumer field, or application field that contains the customer identifier, e.g. 'x-customer-id'
      - `look_up_value_in` 'application' | 'consumer' | 'header' | 'query' — Where to find the customer identifier in the request.
    - `deny_unknown_customers` boolean — If set to true, gateway will deny access to any unknown subjects.
    - `entitlement_access_endpoint` string, required — A string representing a URL, such as https://example.com/path/to/resource?q=search.
    - `fail_policy` 'allow' | 'block' — Policy to apply when enforcement state cannot be retrieved.
    - `feature` object, required — The feature identifies what capability is being accessed and enforced.
      - `key` string, required — The feature key
    - `keepalive` number — How long in milliseconds an idle connection to the entitlement access endpoint is kept open before being closed.
    - `l1_cache_ttl_seconds` number — Time in seconds to keep enforcement state in Kong's local L1 cache
    - `l2_cache_ttl_seconds` number — Time in seconds to keep enforcement state in Redis
    - `max_stale_seconds` number — Maximum age in seconds of cached enforcement state before it is considered stale and must be refreshed from Redis
    - `redis` object, nullable
      - `cloud_authentication` object, nullable — Cloud auth related configs for connecting to a Cloud Provider's Redis instance.
        - `auth_provider` 'aws' | 'azure' | 'gcp' | 'oauth' — Auth providers to be used to authenticate to a Cloud Provider's Redis instance.
        - `aws_access_key_id` string, nullable — AWS Access Key ID to be used for authentication when `auth_provider` is set to `aws`.
        - `aws_assume_role_arn` string, nullable — The ARN of the IAM role to assume for generating ElastiCache IAM authentication tokens.
        - `aws_cache_name` string, nullable — The name of the AWS Elasticache cluster when `auth_provider` is set to `aws`.
        - `aws_is_serverless` boolean — This flag specifies whether the cluster is serverless when auth_provider is set to `aws`.
        - `aws_region` string, nullable — The region of the AWS ElastiCache cluster when `auth_provider` is set to `aws`.
        - `aws_role_session_name` string, nullable — The session name for the temporary credentials when assuming the IAM role.
        - `aws_secret_access_key` string, nullable — AWS Secret Access Key to be used for authentication when `auth_provider` is set to `aws`.
        - `azure_client_id` string, nullable — Azure Client ID to be used for authentication when `auth_provider` is set to `azure`.
        - `azure_client_secret` string, nullable — Azure Client Secret to be used for authentication when `auth_provider` is set to `azure`.
        - `azure_tenant_id` string, nullable — Azure Tenant ID to be used for authentication when `auth_provider` is set to `azure`.
        - `gcp_service_account_json` string, nullable — GCP Service Account JSON to be used for authentication when `auth_provider` is set to `gcp`.
        - `oauth` object, nullable — OAuth 2.0 client configuration used to authenticate to Redis when `auth_provider` is set to `oauth`.
          - `auth_method` 'client_secret_basic' | 'client_secret_jwt' | 'client_secret_post' — Client authentication method used against the token endpoint.
          - `client_id` string, nullable — OAuth 2.0 client ID.
          - `client_secret` string, nullable — OAuth 2.0 client secret.
          - `client_secret_jwt_alg` 'HS256' | 'HS512' — Signing algorithm used for `client_secret_jwt` client authentication.
          - `grant_type` 'client_credentials' | 'password' — OAuth 2.0 grant type used to request access tokens.
          - `password` string, nullable — Resource owner password, used with the `password` grant type.
          - `redis_username` string, nullable — Static Redis ACL username sent with `AUTH <username> <token>`.
          - `redis_username_claim` string, nullable — JWT claim in the access token used to derive the Redis ACL username (for example, `oid` for Microsoft Entra ID).
          - `scopes` string[] — OAuth 2.0 scopes to request.
          - `ssl_verify` boolean — Whether to verify the TLS certificate of the token endpoint.
          - `timeout` integer — Timeout, in milliseconds, for requests to the token endpoint.
          - `token_endpoint` string, nullable — OAuth 2.0 token endpoint URL used to request access tokens.
          - `token_headers` object, nullable — Additional HTTP headers to send with the token request.
          - `token_post_args` object, nullable — Additional POST body arguments to send with the token request.
          - `username` string, nullable — Resource owner username, used with the `password` grant type.
      - `cluster_max_redirections` integer — Maximum retry attempts for redirection.
      - `cluster_nodes` object[], nullable — Cluster addresses to use for Redis connections when the `redis` strategy is defined. Defining this field implies using a Redis Cluster. The minimum length of the array is 1 element.
        - `ip` string — A string representing a host name, such as example.com.
        - `port` integer — An integer representing a port number between 0 and 65535, inclusive.
      - `connect_timeout` integer — An integer representing a timeout in milliseconds. Must be between 0 and 2^31-2.
      - `connection_is_proxied` boolean — If the connection to Redis is proxied (e.g. Envoy), set it `true`. Set the `host` and `port` to point to the proxy address.
      - `database` integer — Database to use for the Redis connection when using the `redis` strategy
      - `host` string — A string representing a host name, such as example.com.
      - `keepalive_backlog` integer, nullable — Limits the total number of opened connections for a pool. If the connection pool is full, connection queues above the limit go into the backlog queue. If the backlog queue is full, subsequent connect operations fail and return `nil`. Queued operations (subject to set timeouts) resume once the number of connections in the pool is less than `keepalive_pool_size`. If latency is high or throughput is low, try increasing this value. Empirically, this value is larger than `keepalive_pool_size`.
      - `keepalive_pool_size` integer — The size limit for every cosocket connection pool associated with every remote server, per worker process. If neither `keepalive_pool_size` nor `keepalive_backlog` is specified, no pool is created. If `keepalive_pool_size` isn't specified but `keepalive_backlog` is specified, then the pool uses the default value. Try to increase (e.g. 512) this value if latency is high or throughput is low.
      - `password` string, nullable — Password to use for Redis connections. If undefined, no AUTH commands are sent to Redis.
      - `port` string — An integer representing a port number between 0 and 65535, inclusive.
      - `read_timeout` integer — An integer representing a timeout in milliseconds. Must be between 0 and 2^31-2.
      - `send_timeout` integer — An integer representing a timeout in milliseconds. Must be between 0 and 2^31-2.
      - `sentinel_master` string, nullable — Sentinel master to use for Redis connections. Defining this value implies using Redis Sentinel.
      - `sentinel_nodes` object[], nullable — Sentinel node addresses to use for Redis connections when the `redis` strategy is defined. Defining this field implies using a Redis Sentinel. The minimum length of the array is 1 element.
        - `host` string — A string representing a host name, such as example.com.
        - `port` integer — An integer representing a port number between 0 and 65535, inclusive.
      - `sentinel_password` string, nullable — Sentinel password to authenticate with a Redis Sentinel instance. If undefined, no AUTH commands are sent to Redis Sentinels.
      - `sentinel_role` 'any' | 'master' | 'slave' — Sentinel role to use for Redis connections when the `redis` strategy is defined. Defining this value implies using Redis Sentinel.
      - `sentinel_username` string, nullable — Sentinel username to authenticate with a Redis Sentinel instance. If undefined, ACL authentication won't be performed. This requires Redis v6.2.0+.
      - `server_name` string, nullable — A string representing an SNI (server name indication) value for TLS.
      - `ssl` boolean — If set to true, uses SSL to connect to Redis.
      - `ssl_verify` boolean — If set to true, verifies the validity of the server SSL certificate. If setting this parameter, also configure `lua_ssl_trusted_certificate` in `kong.conf` to specify the CA (or server) certificate used by your Redis server. You may also need to configure `lua_ssl_verify_depth` accordingly.
      - `username` string, nullable — Username to use for Redis connections. If undefined, ACL authentication won't be performed. This requires Redis v6.0.0+. To be compatible with Redis v5.x.y, you can set it to `default`.
    - `refresh_interval` number — How often in seconds to poll enforcement state from the entitlement access endpoint
    - `response_codes` object
      - `CUSTOMER_NOT_FOUND` object
        - `http_status` number — Status code to return when enforcement is triggered.
        - `message` string — Message to return when enforcement is triggered.
      - `FEATURE_NOT_FOUND` object
        - `http_status` number — Status code to return when enforcement is triggered.
        - `message` string — Message to return when enforcement is triggered.
      - `FEATURE_UNAVAILABLE` object
        - `http_status` number — Status code to return when enforcement is triggered.
        - `message` string — Message to return when enforcement is triggered.
      - `NO_CREDIT_AVAILABLE` object
        - `http_status` number — Status code to return when enforcement is triggered.
        - `message` string — Message to return when enforcement is triggered.
      - `USAGE_LIMIT_REACHED` object
        - `http_status` number — Status code to return when enforcement is triggered.
        - `message` string — Message to return when enforcement is triggered.
    - `ssl_verify` boolean — Verify the TLS certificate presented by the entitlement access endpoint.
    - `sync_rate` number — How often in seconds to sync enforcement state from redis
    - `timeout` number — Maximum time in milliseconds to wait for a response from the entitlement access endpoint.
  - `consumer` object, nullable — If set, the plugin will activate only for requests where the specified has been authenticated. (Note that some plugins can not be restricted to consumers this way.). Leave unset for the plugin to activate regardless of the authenticated Consumer.
    - `id` string
  - `protocols` string[] — A set of strings representing HTTP protocols.
  - `route` object, nullable — If set, the plugin will only activate when receiving requests via the specified route. Leave unset for the plugin to activate regardless of the route being used.
    - `id` string
  - `service` object, nullable — If set, the plugin will only activate when receiving requests via one of the routes belonging to the specified Service. Leave unset for the plugin to activate regardless of the Service being matched.
    - `id` string

## Other responses

- `401` — Unauthorized

## Changes

- **2026-09-25** `4a02153f2e60` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/kong/apis/konnect-api/changes/v2/control-planes/:controlPlaneId/core-entities/plugins#EntitlementEnforcement/post.md)

---

[API](https://skmtc.dev/kong/apis/konnect-api.md) · [All operations](https://skmtc.dev/kong/apis/konnect-api/llms.txt) · [OpenAPI document](https://skmtc.dev/kong/apis/konnect-api/revisions/4a02153f2e60?raw)