---
layout: docs
page_title: Vault Agent API Proxy
description: >-
  Vault Agent's API Proxy functionality allows you to use Vault Agent's API as a proxy
  for Vault's API.
---

# Vault Agent API Proxy

Vault Agent's API Proxy functionality allows you to use Vault Agent's API as a proxy
for Vault's API.

## Functionality

The [`listener` stanza](/vault/docs/agent#listener-stanza) for Vault Agent configures a listener for Vault Agent. If
its `role` is not set to `metrics_only`, it will act as a proxy for the Vault server that
has been configured in the [`vault` stanza](/vault/docs/agent#vault-stanza) stanza of Vault Agent. This enables access to the Vault
API from the Agent API, and can be configured to optionally allow or force the automatic use of
the Auto-Auth token for these requests, as described below.

If a `listener` has been configured alongside a `cache` stanza, the API Proxy will
first attempt to utilize the cache subsystem for qualifying requests, before forwarding the
request to Vault. See the [caching docs](/vault/docs/agent/caching) for more information on caching.

## Using Auto-Auth Token

Vault Agent allows for easy authentication to Vault in a wide variety of
environments using [Auto-Auth](/vault/docs/agent/autoauth). By setting the
`use_auto_auth_token` (see below) configuration, clients will not be required
to provide a Vault token to the requests made to the Agent. When this
configuration is set, if the request doesn't already bear a token, then the
auto-auth token will be used to forward the request to the Vault server. This
configuration will be overridden if the request already has a token attached,
in which case, the token present in the request will be used to forward the
request to the Vault server.

## Forcing Auto-Auth Token

Vault Agent can be configured to force the use of the auto-auth token by using
the value `force` for the `use_auto_auth_token` option. This configuration
overrides the default behavior described above in [Using Auto-Auth
Token](/vault/docs/agent/apiproxy#using-auto-auth-token), and instead ignores any
existing Vault token in the request and instead uses the auto-auth token.


## Configuration (`api_proxy`)

The top level `api_proxy` block has the following configuration entries:

- `use_auto_auth_token` `(bool/string: false)` - If set, the requests made to Agent
without a Vault token will be forwarded to the Vault server with the
auto-auth token attached. If the requests already bear a token, this
configuration will be overridden and the token in the request will be used to
forward the request to the Vault server. If set to `"force"` Agent will use the
auto-auth token, overwriting the attached Vault token if set.

The following two `api_proxy` options are only useful when making requests to a Vault
Enterprise cluster, and are documented as part of its
[Eventual Consistency](/vault/docs/enterprise/consistency#vault-agent-and-consistency-headers)
page.

- `enforce_consistency` `(string: "never")` - Set to one of `"always"`
or `"never"`.

- `when_inconsistent` `(string: optional)` - Set to one of `"fail"`, `"retry"`,
or `"forward"`.

### Example Configuration

Here is an example of a `listener` configuration alongside `api_proxy` configuration to force the use of the auto_auth token
and enforce consistency.

```hcl
# Other Vault Agent configuration blocks
# ...

api_proxy {
  use_auto_auth_token = "force"
  enforce_consistency = "always"
}

listener "tcp" {
    address = "127.0.0.1:8100"
    tls_disable = true
}
```