---
layout: docs
page_title: API Gateway configuration reference
description: Learn how to configure a Consul API gateway on VMs.
---

# API gateway configuration reference

This topic provides reference information for the API gateway configuration entry that you can deploy to networks in virtual machine (VM) environments. For reference information about configuring Consul API gateways on Kubernetes, refer to [Gateway Resource Configuration](/consul/docs/connect/gateways/api-gateway/configuration/gateway).

## Introduction

A gateway is a type of network infrastructure that determines how service traffic should be handled. Gateways contain one or more listeners that bind to a set of hosts and ports. An HTTP Route or TCP Route can then attach to a gateway listener to direct traffic from the gateway to a service.

## Configuration model

The following list outlines field hierarchy, language-specific data types, and requirements in an `api-gateway` configuration entry. Click on a property name to view additional details, including default values.

- [`Kind`](#kind): string | must be `"api-gateway"`
- [`Name`](#name): string | no default
- [`Namespace`](#namespace): string | no default <EnterpriseAlert inline />
- [`Partition`](#partition): string | no default <EnterpriseAlert inline />
- [`Meta`](#meta): map | no default
- [`Listeners`](#listeners): list of objects | no default
  - [`Name`](#listeners-name): string | no default
  - [`Port`](#listeners-port): number | no default
  - [`Hostname`](#listeners-hostname): string | `"*"`
  - [`Protocol`](#listeners-protocol): string | `"tcp"`
  - [`TLS`](#listeners-tls): map | none
    - [`MinVersion`](#listeners-tls-minversion): string | no default
    - [`MaxVersion`](#listeners-tls-maxversion): string | no default
    - [`CipherSuites`](#listeners-tls-ciphersuites): list of strings | Envoy default cipher suites
    - [`Certificates`](#listeners-tls-certificates): list of objects | no default
      - [`Kind`](#listeners-tls-certificates-kind): string | no default
      - [`Name`](#listeners-tls-certificates-name): string | no default
      - [`Namespace`](#listeners-tls-certificates-namespace): string | no default <EnterpriseAlert inline />
      - [`Partition`](#listeners-tls-certificates-partition): string | no default <EnterpriseAlert inline />
  - [`default`](#listeners-default): map
    - [`JWT`](#listeners-default-jwt): map
      - [`Providers`](#listeners-default-jwt-providers): list
        - [`Name`](#listeners-default-jwt-providers): string
          - [`VerifyClaims`](#listeners-default-jwt-providers): map
              - [`Path`](#listeners-default-jwt-providers): list
              - [`Value`](#listeners-default-jwt-providers): string
  - [`override`](#listeners-override): map
    - [`JWT`](#listeners-override-jwt): map
      - [`Providers`](#listeners-override-jwt-providers): list
        - [`Name`](#listeners-override-jwt-providers): string
          - [`VerifyClaims`](#listeners-override-jwt-providers): map
            - [`Path`](#listeners-override-jwt-providers): list
            - [`Value`](#listeners-override-jwt-providers): string



## Complete configuration

When every field is defined, an `api-gateway` configuration entry has the following form:

<CodeTabs>

```hcl
Kind = "api-gateway"
Name = "<name of api gateway>"
Namespace = "<enterprise: namespace of the gateway>"
Partition = "<enterprise: partition of the gateway>"

Meta = {
  <any key> = "<any value>"
}

Listeners = [
  {
    Port = <external service port>
    Name = "<unique name for this listener>"
    Protocol = "<protocol used by external service>"
    TLS = {
      MaxVersion = "<version of TLS>"
      MinVersion = "<version of TLS>"
      CipherSuites = [
        "<cipher suite>"
      ]
      Certificates = [
        {
          Kind = "file-system-certificate"
          Name = "<name of file-system-certificate>"
          Namespace = "<enterprise: namespace of the certificate>"
          Partition = "<enterprise: partition of the certificate>"
        }
      ]
    }
    default = {
     JWT = {
      Providers = [
        Name = "<provider>"
        VerifyClaims = {
          Path = ["<path to claim>"]
          Value = "<value of claim>"
        }
      ]
     }
    }
    override = {
     JWT = {
      Providers = [
        Name = "<provider>"
        VerifyClaims = {
          Path = ["<path to claim>"]
          Value = "<value of claim>"
        }
      ]
     }
    }
  }
]
```

```json
{
  "Kind": "api-gateway",
  "Name": "<name of api gateway>",
  "Namespace": "<enterprise: namespace of the gateway>",
  "Partition": "<enterprise: partition of the gateway>",
  "Meta": {
    "<any key>": "<any value>"
  },
  "Listeners": [
    {
      "Name": "<unique name for this listener>",
      "Port": <external service port>,
      "Protocol": "<protocol used by external service>",
      "TLS": {
        "MaxVersion": "<version of TLS>",
        "MinVersion": "<version of TLS>",
        "CipherSuites": [
          "<cipher suite>"
        ],
        "Certificates": [
          {
            "Kind": "file-system-certificate",
            "Name": "<name of file-system-certificate>",
            "Namespace": "<enterprise: namespace of the certificate>",
            "Partition": "<enterprise: partition of the certificate>"
          }
        ]
      }
    },
    {
      "default": {
        "JWT": {
          "Providers": [
            {
              "Name": "<name of provider>",
              "VerifyClaims": {
                "Path": ["<path to claim>"],
                "Value": "<value of the claim>"
              }
            }
          ]
        }
      }
    },
    {
      "override": {
        "JWT": {
          "Providers": [
            {
              "Name": "<name of provider>",
              "VerifyClaims": {
                "Path": ["<path to claim>"],
                "Value": "<value of the claim>"
              }
            }
          ]
        }
      }
    }
  ]
}
```

</CodeTabs>

## Specification

This section provides details about the fields you can configure in the
`api-gateway` configuration entry.

### `Kind`

Specifies the type of configuration entry to implement. This must be
`api-gateway`.

#### Values

- Default: none
- This field is required.
- Data type: string value that must be set to `"api-gateway"`.

### `Name`

Specifies a name for the configuration entry. The name is metadata that you can
use to reference the configuration entry when performing Consul operations,
such as applying a configuration entry to a specific cluster.

#### Values

- Default: none
- This field is required.
- Data type: string

### `Namespace` <EnterpriseAlert inline />

Specifies the Enterprise [namespace](/consul/docs/enterprise/namespaces) to apply to the configuration entry.

#### Values

- Default: `"default"` in Enterprise
- Data type: string

### `Partition` <EnterpriseAlert inline />

Specifies the Enterprise [admin partition](/consul/docs/enterprise/admin-partitions) to apply to the configuration entry.

#### Values

- Default: `"default"` in Enterprise
- Data type: string

### `Meta`

Specifies an arbitrary set of key-value pairs to associate with the gateway.

#### Values

- Default: none
- Data type: map containing one or more keys and string values.

### `Listeners[]`

Specifies a list of listeners that gateway should set up. Listeners are
uniquely identified by their port number.

#### Values

- Default: none
- This field is required.
- Data type: List of maps. Each member of the list contains the following fields:
  - [`Name`](#listeners-name)
  - [`Port`](#listeners-port)
  - [`Hostname`](#listeners-hostname)
  - [`Protocol`](#listeners-protocol)
  - [`TLS`](#listeners-tls)

### `Listeners[].Name`

Specifies the unique name for the listener. This field accepts letters, numbers, and hyphens.

#### Values

- Default: none
- This field is required.
- Data type: string

### `Listeners[].Port`

Specifies the port number that the listener receives traffic on.

#### Values

- Default: `0`
- This field is required.
- Data type: integer

### `Listeners[].Hostname`

Specifies the hostname that the listener receives traffic on.

#### Values

- Default: `"*"`
- This field is optional.
- Data type: string

### `Listeners[].Protocol`

Specifies the protocol associated with the listener.

#### Values

- Default: none
- This field is required.
- The data type is one of the following string values: `"tcp"` or `"http"`.

### `Listeners[].TLS`

Specifies the TLS configurations for the listener.

#### Values

- Default: none
- Map that contains the following fields:
  - [`MaxVersion`](#listeners-tls-maxversion)
  - [`MinVersion`](#listeners-tls-minversion)
  - [`CipherSuites`](#listeners-tls-ciphersuites)
  - [`Certificates`](#listeners-tls-certificates)

### `Listeners[].TLS.MaxVersion`

Specifies the maximum TLS version supported for the listener.

#### Values

- Default depends on the version of Envoy:
  - Envoy 1.22.0 and later default to `TLSv1_2`
  - Older versions of Envoy default to `TLSv1_0`
- Data type is one of the following string values:
  - `TLS_AUTO`
  - `TLSv1_0`
  - `TLSv1_1`
  - `TLSv1_2`
  - `TLSv1_3`

### `Listeners[].TLS.MinVersion`

Specifies the minimum TLS version supported for the listener.

#### Values

- Default: none
- Data type is one of the following string values:
  - `TLS_AUTO`
  - `TLSv1_0`
  - `TLSv1_1`
  - `TLSv1_2`
  - `TLSv1_3`

### `Listeners[].TLS.CipherSuites[]`

Specifies a list of cipher suites that the listener supports when negotiating connections using TLS 1.2 or older.

#### Values

- Defaults to the ciphers supported by the version of Envoy in use. Refer to the
  [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/transport_sockets/tls/v3/common.proto#envoy-v3-api-field-extensions-transport-sockets-tls-v3-tlsparameters-cipher-suites)
  for details.
- Data type: List of string values. Refer to the
  [Consul repository](https://github.com/hashicorp/consul/blob/v1.11.2/types/tls.go#L154-L169)
  for a list of supported ciphers.

### `Listeners[].TLS.Certificates[]`

The list of references to [file system](/consul/docs/connect/config-entries/file-system-certificate) or [inline certificates](/consul/docs/connect/config-entries/inline-certificate) that the listener uses for TLS termination. You should create the configuration entry for the certificate separately and then reference the configuration entry in the `Name` field.

#### Values

- Default: None
- Data type: List of maps. Each member of the list has the following fields:
  - [`Kind`](#listeners-tls-certificates-kind)
  - [`Name`](#listeners-tls-certificates-name)
  - [`Namespace`](#listeners-tls-certificates-namespace) <EnterpriseAlert inline />
  - [`Partition`](#listeners-tls-certificates-partition) <EnterpriseAlert inline />

### `Listeners[].TLS.Certificates[].Kind`

The list of references to certificates that the listener uses for TLS termination.

#### Values

- Default: None
- This field is required.
- The data type is one of the following string values: `"file-system-certificate"` or `"inline-certificate"`.

### `Listeners[].TLS.Certificates[].Name`

Specifies the name of the [file system certificate](/consul/docs/connect/config-entries/file-system-certificate) or [inline certificate](/consul/docs/connect/config-entries/inline-certificate) that the listener uses for TLS termination.

#### Values

- Default: None
- This field is required.
- Data type: string

### `Listeners[].TLS.Certificates[].Namespace` <EnterpriseAlert inline />

Specifies the Enterprise [namespace](/consul/docs/enterprise/namespaces) where the certificate can be found.

#### Values

- Default: `"default"` in Enterprise
- Data type: string

### `Listeners[].TLS.Certificates[].Partition` <EnterpriseAlert inline />

Specifies the Enterprise [admin partition](/consul/docs/enterprise/admin-partitions) where the certificate can be found.

#### Values

- Default: `"default"` in Enterprise
- Data type: string

### `Listeners[].default`

Specifies a block of default configurations to apply to the gateway listener. All routes attached to the listener inherit the default configurations. You can specify override configurations that have precedence over default configurations in the [`override` block](#listeners-override) as well as in the `JWT` block in the [HTTP route configuration entry](/consul/docs/connect/config-entries/http-route).

#### Values

- Default: None
- Data type: Map

### `Listeners[].default{}.JWT`

Specifies a block of default JWT verification configurations to apply to the gateway listener. Specify configurations that have precedence over the defaults in either the [`override.JWT` block](#listeners-override) or in the [`JWT` block](/consul/docs/connect/config-entries/http-route#rules-filters-jwt) in the HTTP route configuration. Refer to [Use JWTs to verify requests to API gateways](/consul/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-vms) for order of precedence and other details about using JWT verification in API gateways.

#### Values

- Default: None
- Data type: Map

### `Listeners[].default{}.JWT{}.Providers`

Specifies a list of default JWT provider configurations to apply to the gateway listener. A provider configuration contains the name of the provider and claims. Specify configurations that have precedence over the defaults in either the [`override.JWT.Providers` block](#listeners-override-providers) or in the [`JWT` block](/consul/docs/connect/config-entries/http-route#rules-filters-jwt-providers) of the HTTP route configuration. Refer to [Use JWTs to verify requests to API gateways](/consul/docs/connect/gateways/api-gateway/secure-traffic/verify-jwts-vms) for order of precedence and other details about using JWT verification in API gateways.

#### Values

- Default: None
- Data type: List of maps

The following table describes the parameters you can specify in a member of the `Providers` list:

| Parameter | Description | Data type | Default |
| ---       | ---         | ---       | ---     |
| `Name` | Specifies the name of the provider. | String | None |
| `VerifyClaims` | Specifies a list of paths and a value that define the claim that Consul verifies when it receives a request. The `VerifyClaims` map specifies the following settings: <ul><li>`Path`: Specifies a list of one or more registered or custom claims.</li><li>`Value`: Specifies the expected value of the claim.</li></ul> | Map | None |

Refer to [Configure JWT verification settings](#configure-jwt-verification-settings) for an example configuration.

### `Listeners[].override`

Specifies a block of configurations to apply to the gateway listener. The override settings have precedence over the configurations in the [`Listeners[].default` block](#listeners-default).

#### Values

- Default: None
- Data type: Map

### `Listeners[].override{}.JWT`

Specifies a block of JWT verification configurations to apply to the gateway listener. The override settings have precedence over the [`Listeners[].default` configurations](#listeners-default) as well as any route-specific JWT configurations.

#### Values

- Default: None
- Data type: Map

### `Listeners[].override{}.JWT{}.Providers`

Specifies a list of JWT provider configurations to apply to the gateway listener. A provider configuration contains the name of the provider and claims. The override settings have precedence over `Listeners[].defaults{}.JWT{}.Providers` as well as any listener-specific configuration.

#### Values

- Default: None
- Data type: List of maps

The following table describes the parameters you can specify in a member of the `Providers` list:

| Parameter | Description | Data type | Default |
| ---       | ---         | ---       | ---     |
| `Name` | Specifies the name of the provider. | String | None |
| `VerifyClaims` | Specifies a list of paths and a value that define the claim that Consul verifies when it receives a request. The `VerifyClaims` map specifies the following settings: <ul><li>`Path`: Specifies a list of one or more registered or custom claims.</li><li>`Value`: Specifies the expected value of the claim.</li></ul> | Map | None |

Refer to [Configure JWT verification settings](#configure-jwt-verification-settings) for an example configuration.

## Examples

The following examples demonstrate common API gateway configuration patterns for specific use cases.

### Configure JWT verification settings

The following example configures `listener-one` to verify that requests include a token with Okta user permissions by default. The listener also verifies that the token has an audience of `api.apps.organization.com`.

<Tabs>
<Tab heading="HCL" group="hcl">

```hcl
Kind = "api-gateway"
Name = "api-gateway"
Listeners = [
    {
        name = "listener-one"
        port     = 9001
        protocol = "http"
        # override and default are backed by the same type of data structure, see the following section for more on how they interact
        override = {
            JWT = {
                Providers = [
                    {
                        Name = "okta",
                        VerifyClaims = {
                            Path = ["aud"],
                            Value = "api.apps.organization.com",
                        }
                    },
                ]
            }
        }
        default = {
            JWT = {
                Providers = [
                     {
                        Name = "okta",
                        VerifyClaims = {
                            Path = ["perms", "role"],
                            Value = "user",
                        }
                    }
                ]
            }
        }
    }
]
```
</Tab>
<Tab heading="JSON" group="json">

```json
{
  "Kind": "api-gateway",
  "Name": "api-gateway",
  "Listeners": [
    {
      "name": "listener-one",
      "port": 9001,
      "protocol": "http",
      "override": {
        "JWT": {
          "Providers": [{
            "Name": "okta",
            "VerifyClaims": {
              "Path": ["aud"],
              "Value": "api.apps.organization.com"
            }
          }]
        }
      },
      "default": {
        "JWT": {
          "Providers": [{
              "Name": "okta",
              "VerifyClaims": {
                "Path": ["perms", "role"],
                "Value": "user"
              }
            }]
          }
        }
      }
    ]
}
```

</Tab>
</Tabs>