Skip to main content
API7.ai Logo

Secrets

In this document, you will learn the basic concept of secrets in APISIX and why you may need them.

Explore additional resources at the end of the document for more information on related topics.

Overview​

In APISIX, a secret object is used to set up integration with an external secret manager, so that APISIX can establish connections and fetch secrets from the secret manager dynamically at runtime.

The following diagram illustrates the concept of a secret object using an example, where key-auth is enabled for a user, John, and user credentials are stored in a HashiCorp Vault server:

secrets diagram example when using Vault as the external secret manager to store key for key authentication

As demonstrated, when APISIX is used in conjunction with an external secret manager, the field for secret is defined as a variable starting with a fixed prefix $secret://, appended with the name of the secret manager, APISIX secret object ID, username, and other details.

Specifically, if Vault is used as the secret manager, the APISIX secret object should specify:

  • uri: location where Vault server is hosted
  • prefix: path prefix corresponding to a secret engine that Vault should route traffic to
  • token: token for APISIX to authenticate to Vault and establish connection

These configurations ensure that John can send requests to APISIX and access the back-end service with the correct key. Requests from unauthenticated users are rejected by APISIX.

In addition to Vault, APISIX integrates with AWS Secrets Manager and Google Cloud Secret Manager. Secret references use $secret://...; environment references use $env://... or $ENV://....

Supported Fields and Resolution​

Secret and environment references can be used in these string fields:

  • HTTP and stream plugin configuration fields;
  • consumer authentication plugin fields; and
  • cert, key, certs, keys, and client.ca in SSL resources.

SSL resource references are resolved during HTTP and Stream TLS handshakes. An upstream client SSL resource can therefore store $secret://... or $env://... references in cert and key and be selected by upstream.tls.client_cert_id for HTTP or Stream upstream mTLS.

APISIX recognizes a reference before ordinary string validation. It therefore allows the placeholder to bypass constraints such as enum, pattern, minLength, and maxLength. The resolved value is not validated against those constraints again. Make sure the value stored in the secret manager is valid for the target field, including its format and length.

Plugin references are resolved immediately before plugin execution. APISIX caches resolved values and refreshes the resolved plugin configuration when a cached value changes. Successful lookups and lookup failures use separate cache limits and TTLs under apisix.lru.secret in config.yaml.

If APISIX cannot resolve a reference, it logs an error such as failed to resolve secret reference and normally leaves the original reference string in the configuration passed to the plugin. The resulting request behavior depends on the field and plugin and can include an upstream connection error or another plugin-specific error.

Consumer authentication fails closed. If a Consumer credential is missing or still contains an unresolved secret reference, APISIX excludes that Consumer from the credential lookup. A client cannot authenticate by sending the literal $secret://... or $env://... reference and receives the authentication plugin's normal invalid-credential response.

Monitor resolution errors and test secret rotation before relying on a new value.

Resolve AWS Secret Names with Slashes​

AWS Secrets Manager secret names can contain slashes, which makes the boundary between the secret name and an optional JSON field ambiguous. APISIX tries the longest possible secret name first. Only when AWS returns ResourceNotFoundException does it move path segments from the right into the field name and try a shorter secret name.

For example, $secret://aws/1/john/secret/john-key-auth tries these interpretations in order:

  1. Secret john/secret/john-key-auth, with no JSON field.
  2. Secret john/secret, with JSON field john-key-auth.
  3. Secret john, with JSON field secret/john-key-auth.

The longest matching secret name takes precedence. An AWS error other than ResourceNotFoundException stops resolution instead of trying a shorter name.

For configuration examples, see Manage Secrets in HashiCorp Vault. For the secret object schema used by Vault, AWS, and Google Cloud integrations, see the Admin API reference.

Additional Resources​