diff --git a/docs/configuration/secret-files.md b/docs/configuration/secret-files.md
index 1eba28327..d49ca7b64 100644
--- a/docs/configuration/secret-files.md
+++ b/docs/configuration/secret-files.md
@@ -29,14 +29,14 @@ flowchart LR
 
 ## Configuration
 
-| Environment variable | Description | Default |
-| --- | --- | --- |
-| `AIDBOX_VAULT_CONFIG` | Path to the vault config JSON file that maps named secrets to file paths and resource scopes. | empty (feature disabled) |
+| Environment variable | Description                                                                                   | Default                  |
+|----------------------|-----------------------------------------------------------------------------------------------|--------------------------|
+| `BOX_VAULT_CONFIG`   | Path to the vault config JSON file that maps named secrets to file paths and resource scopes. | empty (feature disabled) |
 
 See [Aidbox Settings Reference](../reference/all-settings.md) for the full list of environment variables.
 
 {% hint style="warning" %}
-This setting requires a restart to take effect. The config file itself is re-read automatically when modified — no restart needed for config changes.
+This setting requires a restart to take effect. The config file is loaded once — restart is required after changing the vault config.
 {% endhint %}
 
 ### Vault config file format
@@ -47,15 +47,15 @@ This setting requires a restart to take effect. The config file itself is re-rea
   "secret": {
     "client-secret": {
       "path": "/run/secrets/client-secret",
-      "scope": ["Client/my-client"]
+      "scope": {"resource_type": "Client", "id": "my-client"}
     },
     "kafka-jaas": {
       "path": "/run/secrets/kafka-jaas",
-      "scope": ["AidboxTopicDestination/kafka-dest-1"]
+      "scope": {"resource_type": "AidboxTopicDestination", "id": "kafka-dest-1"}
     },
     "jwt-key": {
       "path": "/run/secrets/jwt-key",
-      "scope": ["TokenIntrospector"]
+      "scope": {"resource_type": "TokenIntrospector"}
     }
   }
 }
@@ -64,7 +64,7 @@ This setting requires a restart to take effect. The config file itself is re-rea
 
 Each entry under `"secret"` maps a secret name to:
 
-<table><thead><tr><th width="100">Field</th><th>Description</th></tr></thead><tbody><tr><td><code>path</code></td><td>Absolute path to the file containing the secret value</td></tr><tr><td><code>scope</code></td><td>Array of resource references that are allowed to access this secret. Entries can be <code>"ResourceType/id"</code> (specific instance, e.g. <code>"Client/my-client"</code>) or <code>"ResourceType"</code> (any instance of that type, e.g. <code>"Client"</code>)</td></tr></tbody></table>
+<table><thead><tr><th width="100">Field</th><th>Description</th></tr></thead><tbody><tr><td><code>path</code></td><td>Absolute path to the file containing the secret value</td></tr><tr><td><code>scope</code></td><td>Object identifying the resource allowed to access this secret. Use <code>resource_type</code> and <code>id</code> to restrict to a specific instance (e.g. <code>{"resource_type": "Client", "id": "my-client"}</code>), or <code>resource_type</code> alone to allow any instance of that type (e.g. <code>{"resource_type": "TokenIntrospector"}</code>)</td></tr></tbody></table>
 
 ## Extension pattern
 
@@ -135,25 +135,25 @@ This works with any mechanism that updates files in place — Kubernetes Secrets
 
 The following fields support secret references via the extension pattern:
 
-| Resource | Field | Description |
-| --- | --- | --- |
-| **Client** | `secret` | Client secret for authentication |
-| **IdentityProvider** | `client.secret` | Client secret for symmetric authentication |
-| **IdentityProvider** | `client.private-key` | Private key for asymmetric authentication |
-| **IdentityProvider** | `client.certificate` | Certificate for asymmetric authentication |
-| **TokenIntrospector** | `jwt.secret` | Shared secret key for JWT verification |
-| **TokenIntrospector** | `jwt.keys.k` | Symmetric key for validation |
-| **TokenIntrospector** | `introspection_endpoint.authorization` | Authorization header value |
-| **AidboxTopicDestination** | `parameter.saslJaasConfig` | SASL JAAS configuration for Kafka authentication |
-| **AidboxTopicDestination** | `parameter.sslKeystoreKey` | SSL keystore private key for Kafka connection |
+| Resource                   | Field                                  | Description                                      |
+|----------------------------|----------------------------------------|--------------------------------------------------|
+| **Client**                 | `secret`                               | Client secret for authentication                 |
+| **IdentityProvider**       | `client.secret`                        | Client secret for symmetric authentication       |
+| **IdentityProvider**       | `client.private-key`                   | Private key for asymmetric authentication        |
+| **IdentityProvider**       | `client.certificate`                   | Certificate for asymmetric authentication        |
+| **TokenIntrospector**      | `jwt.secret`                           | Shared secret key for JWT verification           |
+| **TokenIntrospector**      | `jwt.keys.k`                           | Symmetric key for validation                     |
+| **TokenIntrospector**      | `introspection_endpoint.authorization` | Authorization header value                       |
+| **AidboxTopicDestination** | `parameter.saslJaasConfig`             | SASL JAAS configuration for Kafka authentication |
+| **AidboxTopicDestination** | `parameter.sslKeystoreKey`             | SSL keystore private key for Kafka connection    |
 
 ## Delivering secrets to the filesystem
 
 The external secrets feature is agnostic to how files are placed on the filesystem. Common approaches:
 
-| Method | Description |
-| --- | --- |
-| [Kubernetes Secrets](https://kubernetes.io/docs/concepts/configuration/secret/) | Mounted as volumes in pods |
-| [Secrets Store CSI Driver](https://secrets-store-csi-driver.sigs.k8s.io/) | Mounts secrets from external vaults with automatic rotation. See the [Azure Key Vault](../tutorials/other-tutorials/azure-key-vault-external-secrets.md) and [HashiCorp Vault](../tutorials/other-tutorials/hashicorp-vault-external-secrets.md) tutorials |
-| [Docker Secrets](https://docs.docker.com/engine/swarm/secrets/) | Available at `/run/secrets/` in swarm mode |
-| Docker volumes | Bind-mount a host directory containing secret files |
+| Method                                                                          | Description                                                                                                                                                                                                                                                |
+|---------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| [Kubernetes Secrets](https://kubernetes.io/docs/concepts/configuration/secret/) | Mounted as volumes in pods                                                                                                                                                                                                                                 |
+| [Secrets Store CSI Driver](https://secrets-store-csi-driver.sigs.k8s.io/)       | Mounts secrets from external vaults with automatic rotation. See the [Azure Key Vault](../tutorials/other-tutorials/azure-key-vault-external-secrets.md) and [HashiCorp Vault](../tutorials/other-tutorials/hashicorp-vault-external-secrets.md) tutorials |
+| [Docker Secrets](https://docs.docker.com/engine/swarm/secrets/)                 | Available at `/run/secrets/` in swarm mode                                                                                                                                                                                                                 |
+| Docker volumes                                                                  | Bind-mount a host directory containing secret files                                                                                                                                                                                                        |
diff --git a/docs/reference/all-settings.md b/docs/reference/all-settings.md
index 06ae211a9..645654c1e 100644
--- a/docs/reference/all-settings.md
+++ b/docs/reference/all-settings.md
@@ -900,6 +900,16 @@ Activates debugging features for access policy development, including the `_debu
 
 <details><summary>Details</summary><table data-header-hidden="true"><thead><tr><th width="200"></th><th></th></tr></thead><tbody><tr><td>ID</td><td><code>security.dev-mode</code></td></tr><tr><td>Type</td><td>Bool</td></tr><tr><td>Recommended value</td><td><code>true</code></td></tr><tr><td>Default value</td><td><code>false</code></td></tr><tr><td>Environment variable</td><td><code>BOX_SECURITY_DEV_MODE</code></td></tr><tr><td>Deprecated environment variables</td><td><code>AIDBOX_DEV_MODE</code></td></tr><tr><td>Sensitive</td><td><code>false</code> — value will be visible in plaintext in Admin UI</td></tr><tr><td>Set via</td><td>Admin UI → Settings<br />Environment variables</td></tr><tr><td>Hot reload</td><td><code>true</code> — setting can be changed at runtime</td></tr></tbody></table></details>
 
+### Vault config<a href="#vault-config" id="vault-config"></a>
+
+```yaml
+BOX_VAULT_CONFIG: "/path/to/vault-config.json"
+```
+
+Path to the vault config JSON file that maps named secrets to file paths and resource scopes. When set, Aidbox can reference secrets stored as files on the filesystem instead of keeping them in the database. See [External Secrets](../configuration/secret-files.md) for details.
+
+<details><summary>Details</summary><table data-header-hidden="true"><thead><tr><th width="200"></th><th></th></tr></thead><tbody><tr><td>ID</td><td><code>vault-config</code></td></tr><tr><td>Type</td><td>String</td></tr><tr><td>Default value</td><td>(no default — feature disabled)</td></tr><tr><td>Environment variable</td><td><code>BOX_VAULT_CONFIG</code></td></tr><tr><td>Available from</td><td><code>2602</code></td></tr><tr><td>Sensitive</td><td><code>false</code> — value will be visible in plaintext in Admin UI</td></tr><tr><td>Set via</td><td>Environment variables</td></tr><tr><td>Hot reload</td><td><code>false</code> — setting requires system restart</td></tr></tbody></table></details>
+
 ## Modules
 
 Modules settings
diff --git a/docs/tutorials/other-tutorials/azure-key-vault-external-secrets.md b/docs/tutorials/other-tutorials/azure-key-vault-external-secrets.md
index 8cb2a40bb..7d707c071 100644
--- a/docs/tutorials/other-tutorials/azure-key-vault-external-secrets.md
+++ b/docs/tutorials/other-tutorials/azure-key-vault-external-secrets.md
@@ -188,7 +188,7 @@ data:
       "secret": {
         "client-secret": {
           "path": "/run/azure-secrets/client-secret",
-          "scope": ["Client/basic"]
+          "scope": {"resource_type": "Client", "id": "basic"}
         }
       }
     }
@@ -197,7 +197,7 @@ data:
 
 Each entry under `"secret"` maps a secret name to:
 
-<table><thead><tr><th width="100">Field</th><th>Description</th></tr></thead><tbody><tr><td><code>path</code></td><td>Absolute path to the file containing the secret value</td></tr><tr><td><code>scope</code></td><td>Array of resource references allowed to access this secret. Entries can be <code>"ResourceType/id"</code> (specific instance, e.g. <code>"Client/basic"</code>) or <code>"ResourceType"</code> (any instance of that type, e.g. <code>"Client"</code>)</td></tr></tbody></table>
+<table><thead><tr><th width="100">Field</th><th>Description</th></tr></thead><tbody><tr><td><code>path</code></td><td>Absolute path to the file containing the secret value</td></tr><tr><td><code>scope</code></td><td>Object identifying the resource allowed to access this secret. Use <code>resource_type</code> and <code>id</code> to restrict to a specific instance (e.g. <code>{"resource_type": "Client", "id": "basic"}</code>), or <code>resource_type</code> alone to allow any instance of that type (e.g. <code>{"resource_type": "Client"}</code>)</td></tr></tbody></table>
 
 ## Step 8. Deploy Aidbox
 
diff --git a/docs/tutorials/other-tutorials/hashicorp-vault-external-secrets.md b/docs/tutorials/other-tutorials/hashicorp-vault-external-secrets.md
index d2d743ccd..c4a4c9e45 100644
--- a/docs/tutorials/other-tutorials/hashicorp-vault-external-secrets.md
+++ b/docs/tutorials/other-tutorials/hashicorp-vault-external-secrets.md
@@ -167,7 +167,7 @@ data:
       "secret": {
         "client-secret": {
           "path": "/run/vault-secrets/client-secret",
-          "scope": ["Client/basic"]
+          "scope": {"resource_type": "Client", "id": "basic"}
         }
       }
     }
@@ -176,7 +176,7 @@ data:
 
 Each entry under `"secret"` maps a secret name to:
 
-<table><thead><tr><th width="100">Field</th><th>Description</th></tr></thead><tbody><tr><td><code>path</code></td><td>Absolute path to the file containing the secret value</td></tr><tr><td><code>scope</code></td><td>Array of resource references allowed to access this secret. Entries can be <code>"ResourceType/id"</code> (specific instance, e.g. <code>"Client/basic"</code>) or <code>"ResourceType"</code> (any instance of that type, e.g. <code>"Client"</code>)</td></tr></tbody></table>
+<table><thead><tr><th width="100">Field</th><th>Description</th></tr></thead><tbody><tr><td><code>path</code></td><td>Absolute path to the file containing the secret value</td></tr><tr><td><code>scope</code></td><td>Object identifying the resource allowed to access this secret. Use <code>resource_type</code> and <code>id</code> to restrict to a specific instance (e.g. <code>{"resource_type": "Client", "id": "basic"}</code>), or <code>resource_type</code> alone to allow any instance of that type (e.g. <code>{"resource_type": "Client"}</code>)</td></tr></tbody></table>
 
 ## Step 7. Deploy Aidbox