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.

curl -k "https://localhost:7443/apisix/admin/secret_providers/vault/my-vault?gateway_group_id={group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -d '{
    "uri": "http://vault:8200",
    "prefix": "kv/apisix",
    "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.

curl -k "https://localhost:7443/apisix/admin/secret_providers/aws/my-aws?gateway_group_id={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.

curl -k "https://localhost:7443/apisix/admin/secret_providers/kubernetes/my-k8s?gateway_group_id={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={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={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.