---
title: "Create a HeaderCertAuth plugin"
method: POST
path: "/{workspace}/plugins#HeaderCertAuth"
tags: ["Plugins"]
---

# Create a HeaderCertAuth plugin

`POST /{workspace}/plugins#HeaderCertAuth`

Create a HeaderCertAuth plugin

## Request body

- HeaderCertAuthPlugin — 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` 'header-cert-auth', 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[] — 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
  - `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
    - `allow_partial_chain` boolean — Allow certificate verification with only an intermediate certificate. When this is enabled, you don't need to upload the full chain to Kong Certificates.
    - `anonymous` string — An optional string (consumer UUID or username) value to use as an “anonymous” consumer if authentication fails. If empty (default null), the request fails with an authentication failure `4xx`. Note that this value must refer to the consumer `id` or `username` attribute, and **not** its `custom_id`.
    - `authenticated_group_by` 'CN' | 'DN' — Certificate property to use as the authenticated group. Valid values are `CN` (Common Name) or `DN` (Distinguished Name). Once `skip_consumer_lookup` is applied, any client with a valid certificate can access the Service/API. To restrict usage to only some of the authenticated users, also add the ACL plugin (not covered here) and create allowed or denied groups of users.
    - `ca_certificates` string[], required — List of CA Certificates strings to use as Certificate Authorities (CA) when validating a client certificate. At least one is required but you can specify as many as needed. The value of this array is comprised of primary keys (`id`).
    - `cache_ttl` number — Cache expiry time in seconds.
    - `cert_cache_ttl` number — The length of time in milliseconds between refreshes of the revocation check status cache.
    - `certificate_header_format` 'base64_encoded' | 'url_encoded', required — Format of the certificate header. Supported formats: `base64_encoded`, `url_encoded`.
    - `certificate_header_name` string, required — Name of the header that contains the certificate, received from the WAF or other L7 downstream proxy.
    - `consumer_by` string[] — Whether to match the subject name of the client-supplied certificate against consumer's `username` and/or `custom_id` attribute. If set to `[]` (the empty array), then auto-matching is disabled.
    - `default_consumer` string — The UUID or username of the consumer to use when a trusted client certificate is presented but no consumer matches. Note that this value must refer to the consumer `id` or `username` attribute, and **not** its `custom_id`.
    - `http_proxy_host` string — A string representing a host name, such as example.com.
    - `http_proxy_port` integer — An integer representing a port number between 0 and 65535, inclusive.
    - `http_timeout` number — HTTP timeout threshold in milliseconds when communicating with the OCSP server or downloading CRL.
    - `https_proxy_host` string — A string representing a host name, such as example.com.
    - `https_proxy_port` integer — An integer representing a port number between 0 and 65535, inclusive.
    - `revocation_check_mode` 'IGNORE_CA_ERROR' | 'SKIP' | 'STRICT' — Controls client certificate revocation check behavior. If set to `SKIP`, no revocation check is performed. If set to `IGNORE_CA_ERROR`, the plugin respects the revocation status when either OCSP or CRL URL is set, and doesn't fail on network issues. If set to `STRICT`, the plugin only treats the certificate as valid when it's able to verify the revocation status.
    - `secure_source` boolean — Whether to secure the source of the request. If set to `true`, the plugin will only allow requests from trusted IPs (configured by the `trusted_ips` config option).
    - `skip_consumer_lookup` boolean — Skip consumer lookup once certificate is trusted against the configured CA list.
    - `ssl_verify` boolean — This option enables verification of the certificate presented by the server of the OCSP responder's URL and by the server of the CRL Distribution Point.
  - `protocols` string[] — A set of strings representing HTTP protocols.
  - `route` object — 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 — 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 HeaderCertAuth plugin

- HeaderCertAuthPlugin — 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` 'header-cert-auth', 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[] — 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
  - `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
    - `allow_partial_chain` boolean — Allow certificate verification with only an intermediate certificate. When this is enabled, you don't need to upload the full chain to Kong Certificates.
    - `anonymous` string — An optional string (consumer UUID or username) value to use as an “anonymous” consumer if authentication fails. If empty (default null), the request fails with an authentication failure `4xx`. Note that this value must refer to the consumer `id` or `username` attribute, and **not** its `custom_id`.
    - `authenticated_group_by` 'CN' | 'DN' — Certificate property to use as the authenticated group. Valid values are `CN` (Common Name) or `DN` (Distinguished Name). Once `skip_consumer_lookup` is applied, any client with a valid certificate can access the Service/API. To restrict usage to only some of the authenticated users, also add the ACL plugin (not covered here) and create allowed or denied groups of users.
    - `ca_certificates` string[], required — List of CA Certificates strings to use as Certificate Authorities (CA) when validating a client certificate. At least one is required but you can specify as many as needed. The value of this array is comprised of primary keys (`id`).
    - `cache_ttl` number — Cache expiry time in seconds.
    - `cert_cache_ttl` number — The length of time in milliseconds between refreshes of the revocation check status cache.
    - `certificate_header_format` 'base64_encoded' | 'url_encoded', required — Format of the certificate header. Supported formats: `base64_encoded`, `url_encoded`.
    - `certificate_header_name` string, required — Name of the header that contains the certificate, received from the WAF or other L7 downstream proxy.
    - `consumer_by` string[] — Whether to match the subject name of the client-supplied certificate against consumer's `username` and/or `custom_id` attribute. If set to `[]` (the empty array), then auto-matching is disabled.
    - `default_consumer` string — The UUID or username of the consumer to use when a trusted client certificate is presented but no consumer matches. Note that this value must refer to the consumer `id` or `username` attribute, and **not** its `custom_id`.
    - `http_proxy_host` string — A string representing a host name, such as example.com.
    - `http_proxy_port` integer — An integer representing a port number between 0 and 65535, inclusive.
    - `http_timeout` number — HTTP timeout threshold in milliseconds when communicating with the OCSP server or downloading CRL.
    - `https_proxy_host` string — A string representing a host name, such as example.com.
    - `https_proxy_port` integer — An integer representing a port number between 0 and 65535, inclusive.
    - `revocation_check_mode` 'IGNORE_CA_ERROR' | 'SKIP' | 'STRICT' — Controls client certificate revocation check behavior. If set to `SKIP`, no revocation check is performed. If set to `IGNORE_CA_ERROR`, the plugin respects the revocation status when either OCSP or CRL URL is set, and doesn't fail on network issues. If set to `STRICT`, the plugin only treats the certificate as valid when it's able to verify the revocation status.
    - `secure_source` boolean — Whether to secure the source of the request. If set to `true`, the plugin will only allow requests from trusted IPs (configured by the `trusted_ips` config option).
    - `skip_consumer_lookup` boolean — Skip consumer lookup once certificate is trusted against the configured CA list.
    - `ssl_verify` boolean — This option enables verification of the certificate presented by the server of the OCSP responder's URL and by the server of the CRL Distribution Point.
  - `protocols` string[] — A set of strings representing HTTP protocols.
  - `route` object — 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 — 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

---

[API](https://skmtc.net/kong/apis/kong-enterprise-admin-api.md) · [All operations](https://skmtc.net/kong/apis/kong-enterprise-admin-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/kong/kong-enterprise-admin-api/revisions/28b1f8a59cdc/schema)