Use @akv() for Azure Key Vault secret substitution in Data API builder

Data API builder (DAB) lets you keep secrets, like database connection strings, out of the runtime configuration file by substituting them at load time. Originally this was done with the @env() function for environment variables. Beginning with version 1.6, DAB adds support for Azure Key Vault through the @akv() function.

What @akv() does

You can reference a secret stored in Azure Key Vault directly in the configuration JSON:

{
  "data-source": {
    "connection-string": "@akv('my-connection-secret')"
  }
}

At configuration load time, DAB resolves the placeholder and replaces it with the secret’s value, similar to how @env('VAR_NAME') works. If the secret cannot be retrieved, configuration loading fails. Errors include missing secrets or authorization failures.

Configuration structure

Add the azure-key-vault section at the root level of your configuration:

{
  "azure-key-vault": {
    "endpoint": "https://my-vault-name.vault.azure.net/",
    "retry-policy": {
      "mode": "exponential",
      "max-count": 5,
      "delay-seconds": 2,
      "max-delay-seconds": 30,
      "network-timeout-seconds": 45
    }
  }
}

Properties

Retry policy object

Retry policy modes

Local development: .akv files

For development without an Azure Key Vault, use a .akv file to simulate secrets. Format is name=value per line:

my-connection-secret=Server=.;Database=AppDb;User Id=app;Password=local-dev;
api-key=dev-api-key-123

Guidelines:

• Keep .akv out of source control
• Secret names must match the names used in @akv('name')

Adding Azure Key Vault settings with CLI

You can configure Key Vault settings using the CLI:

dab configure \
  --azure-key-vault.endpoint "https://my-vault.vault.azure.net/" \
  --azure-key-vault.retry-policy.mode exponential \
  --azure-key-vault.retry-policy.max-count 5 \
  --azure-key-vault.retry-policy.delay-seconds 2 \
  --azure-key-vault.retry-policy.max-delay-seconds 30 \
  --azure-key-vault.retry-policy.network-timeout-seconds 45 \
  --config dab-config.json

Validation:

• Retry-policy fields without an endpoint cause validation failure
• Optional retry parameters must be positive integers

Using @akv() in configuration

Basic substitution

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@akv('primary-sql-connection')"
  }
}

Mixed with @env()

{
  "data-source": {
    "database-type": "@env('DB_TYPE')",
    "connection-string": "@akv('sql-connection')"
  },
  "runtime": {
    "rest": { "enabled": true }
  }
}

Stored procedure parameters

{
  "entities": {
    "RunJob": {
      "source": {
        "object": "dbo.RunJob",
        "type": "stored-procedure",
        "parameters": {
          "apiKey": "@akv('job-runner-apikey')"
        }
      },
      "permissions": [
        { "role": "anonymous", "actions": [ "execute" ] }
      ]
    }
  }
}

Troubleshooting

Full example configuration

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@akv('primary-sql-connection')"
  },
  "azure-key-vault": {
    "endpoint": "https://my-vault.vault.azure.net/",
    "retry-policy": {
      "mode": "exponential",
      "max-count": 5,
      "delay-seconds": 2,
      "max-delay-seconds": 30,
      "network-timeout-seconds": 45
    }
  },
  "runtime": {
    "rest": { "enabled": true }
  },
  "entities": {
    "Books": {
      "source": "dbo.Books",
      "permissions": [
        { "role": "anonymous", "actions": [ "read" ] }
      ]
    }
  }
}

Example .akv file:

primary-sql-connection=Server=localhost;Database=BooksDb;User Id=app;Password=password;

Quick reference

Review

Use @akv() to resolve secrets from Azure Key Vault. Configure retry policies for reliability, and use .akv files to simulate secrets in development. This keeps sensitive values out of configuration files while supporting consistent development and production workflows.