| --- |
| layout: docs |
| page_title: Vault Proxy API Proxy |
| description: >- |
| Vault Proxy's API Proxy functionality allows you to use Vault Proxy's API as a proxy |
| for Vault's API. |
| --- |
| |
| # Vault proxy API proxy |
| |
| Vault Proxy's API Proxy functionality allows you to use Vault Proxy's API as a proxy |
| for Vault's API. |
| |
| ## Functionality |
| |
| The [`listener` stanza](/vault/docs/agent#listener-stanza) for Vault Proxy configures a listener for Vault Proxy. 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-and-proxy/proxy#vault-stanza) of Proxy Agent. This enables access to the Vault |
| API from the Proxy 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-and-proxy/proxy/caching) for more information on caching. |
| |
| ## Using Auto-Auth token |
| |
| Vault Proxy allows for easy authentication to Vault in a wide variety of |
| environments using [Auto-Auth](/vault/docs/agent-and-proxy/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 Proxy 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-and-proxy/proxy/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 proxy configuration blocks |
| # ... |
| |
| api_proxy { |
| use_auto_auth_token = "force" |
| enforce_consistency = "always" |
| } |
| |
| listener "tcp" { |
| address = "127.0.0.1:8100" |
| tls_disable = true |
| } |
| ``` |