Configure Secret Management

API7 Enterprise supports secret providers to avoid hardcoding sensitive data like API keys, SSL certificates, and plugin credentials. The $secret:// reference syntax allows you to inject these secrets into gateway resources while keeping the secret values in an external system.

Secret providers are created and managed through the Admin API. ADC does not manage secret providers, but it can reference secrets from an existing provider in supported resources by using $secret://....

Prerequisites

• An API7 Enterprise instance is running.
• A Gateway Group is created and a Gateway instance is running.
• A token from the Dashboard.
• A secret backend if you want to test full secret resolution through the gateway.

Configure a HashiCorp Vault Secret Provider

HashiCorp Vault is a popular choice for managing secrets. You can configure it as a secret provider in API7 Enterprise to store and retrieve credentials.

Start a Vault Instance for Evaluation

Skip this subsection if you already operate Vault and have a scoped token for API7 Enterprise. Otherwise, run a Vault dev-mode container with the KV v1 engine mounted at kv/:

docker run -d --cap-add=IPC_LOCK \
  -e 'VAULT_DEV_LISTEN_ADDRESS=0.0.0.0:8200' \
  -e 'VAULT_ADDR=http://127.0.0.1:8200' \
  -e 'VAULT_DEV_ROOT_TOKEN_ID=api7-quickstart-vault-token' \
  -e 'VAULT_TOKEN=api7-quickstart-vault-token' \
  --name api7-quickstart-vault \
  -p 8200:8200 vault:1.13.0

docker exec api7-quickstart-vault vault secrets enable -path=kv -version=1 kv

To use KV v2 instead, adjust the steps above as follows (a mount path holds one engine, so v1 and v2 cannot coexist at kv/):

• Enable the engine with vault secrets enable -path=kv kv-v2 in place of the -version=1 kv command.
• Use kv/data/api7/* for the policy path, since KV v2 stores secrets under <mount>/data/<path>.
• Set "kv_version": "kv-v2" when registering the provider.

Create a Policy and Token for the Gateway

Grant the gateway read access to the prefix it will reference (kv/api7/*), then mint a token scoped to that policy:

docker exec api7-quickstart-vault /bin/sh -c "echo '
path \"kv/api7/*\" {
    capabilities = [\"read\"]
}
' > /etc/api7-policy.hcl"

docker exec api7-quickstart-vault vault policy write api7-policy /etc/api7-policy.hcl

docker exec api7-quickstart-vault vault token create -policy="api7-policy"

The token create command prints an hvs.... value. Save it — you will pass it to the provider in the next step.

Write a Test Secret

Store one secret under the prefix so the gateway has something to resolve:

docker exec api7-quickstart-vault vault kv put kv/api7/demo key=demo-value

Reference Secrets in Configurations below shows how to consume it as $secret://vault/my-vault/demo/key.

Register the Secret Provider

Register Vault with API7 Enterprise, passing the token from the previous step. Use host.docker.internal rather than 127.0.0.1 so the URL resolves to Vault on the host (inside the gateway container, 127.0.0.1 is the gateway itself). On Docker Desktop this works out of the box; on Docker for Linux, either start the gateway with --add-host=host.docker.internal:host-gateway or attach both containers to the same user-defined network and use the Vault container name (for example http://api7-quickstart-vault:8200).

curl -k "https://localhost:7443/apisix/admin/secret_providers/vault/my-vault?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -d '{
    "uri": "http://host.docker.internal:8200",
    "prefix": "kv/api7",
    "token": "hvs.example-vault-token"
  }'

Configure an AWS Secrets Manager Provider

If your infrastructure is on AWS, you can use AWS Secrets Manager to store your API secrets. Create the secret and the IAM credentials with read access to it by following the AWS Secrets Manager documentation, then register the provider with the resulting access_key_id, secret_access_key, and region:

curl -k "https://localhost:7443/apisix/admin/secret_providers/aws/my-aws?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -d '{
    "access_key_id": "AKIAxxxxxxxx",
    "secret_access_key": "xxxxxxxx",
    "region": "us-east-1"
  }'

Configure a Kubernetes Secrets Provider

For Kubernetes-native deployments, you can use Kubernetes Secrets directly as a provider. Create the Secret and a ServiceAccount with get permission on secrets by following the Kubernetes Secrets documentation, then register the provider with the cluster's API server address and the ServiceAccount token:

curl -k "https://localhost:7443/apisix/admin/secret_providers/kubernetes/my-k8s?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "apiserver_addr": "https://kubernetes.default.svc",
    "token": "example-service-account-token"
  }'

Reference Secrets in Configurations

Once a provider is configured, you can reference its secrets using the $secret://{provider_type}/{provider_id}/{secret_key} syntax.

Use a Secret in an SSL Certificate

You can avoid storing private keys in plain text by referencing them from a secret provider.

Admin API

curl -k "https://localhost:7443/apisix/admin/ssls/example-com-ssl?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "snis": ["example.com"],
    "cert": "$secret://vault/my-vault/ssl/cert",
    "key": "$secret://vault/my-vault/ssl/key"
  }'

ADC

adc.yaml

ssls:
  - id: example-com-ssl
    snis:
      - example.com
    certificates:
      - certificate: "$secret://vault/my-vault/ssl/cert"
        key: "$secret://vault/my-vault/ssl/key"

Use a Secret in a Plugin Configuration

You can also use secrets for plugin credentials, such as the key in the key-auth plugin.

Admin API

curl -k "https://localhost:7443/apisix/admin/consumers/user-1/credentials/user-1-key?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "user-1-key",
    "plugins": {
      "key-auth": {
        "key": "$secret://vault/my-vault/consumer/api-key"
      }
    }
  }'

ADC

adc.yaml

consumers:
  - username: user-1
    credentials:
      - name: user-1-key
        type: key-auth
        config:
          key: "$secret://vault/my-vault/consumer/api-key"

Next Steps

• Configure SSL Certificates — use secrets for SSL cert/key management.
• Manage Gateway Groups — organize your infrastructure.