# Use a Vault Reference > Part of the NocoDB documentation (Product docs > Integrations > Vaults ☁). Index of all pages: https://nocodb.com/llms.txt. Any docs page is available as Markdown by adding `.md` to its URL. URL: https://nocodb.com/docs/product/integrations/vaults/use-a-vault-reference Last updated: 2026-11-11 Point a credential on a NocoDB database connection, AI provider or authentication integration at a secret in a connected Enterprise vault instead of typing the value. A NocoDB vault reference points a credential field at a secret in a connected vault. Once a vault is connected, a credential field can be backed by a secret in that vault instead of holding the value: **Username** and **Password** on a database connection (and, through the API, its TLS key, certificate and CA fields), the **API key** of an AI provider, and the token, password or API-key field of an authentication integration. The form shows **Use a vault** under each field that qualifies. Vault references are available on database connections, AI providers and authentication integrations that take a static credential. OAuth sign-ins, and the sync, channel and action integrations built on them, take their credentials from the provider and cannot use a vault. Who may add a reference is set per vault. By default it is **Workspace Owners** for a workspace vault and the organization's **owners and admins** for an organization vault. An Editor cannot use an integration that holds a reference unless the vault's setting includes them. See [Who can use a vault](/docs/product/integrations/vaults#who-can-use-a-vault). Project roles grant nothing here. ## Add a reference to a connection 1. Create or edit an integration from the workspace **Integrations** page: a database connection, an AI provider or an authentication integration. 2. Under the credential field, click **Use a vault**. That is **Username** or **Password** on a connection, **API key** on an AI provider, or the token or password on an authentication integration. The option appears only under fields that may hold a reference, and only when at least one vault you are allowed to use is visible in this workspace. On a paid plan without the **Enterprise Vaults** add-on, the option shows anyway, with an **Add-on** badge, to people who can manage integrations, and opens **Available as an Enterprise add-on** instead. See [Turning on Enterprise Vaults](/docs/product/integrations/vaults#turning-on-enterprise-vaults). 3. Type the reference in the **Reference** box. It starts with `secrets.` and names the vault, then the secret, then the field inside the secret: ``` secrets.awsProd["nocodb/prod/db/creds"].password ``` Suggestions appear as you type: the vaults you may use after `secrets.`, and with an AWS Secrets Manager vault, that vault's secret names and then the field names inside the chosen secret. The other providers offer no listing, so you type the secret's id as the provider names it. You can always type a value that is not suggested. If you pick an AWS secret that holds several fields and stop there, the box warns: "This secret holds several fields. Pick the one to use, or the connection will fail when it runs." 4. Repeat for the other credential field. 5. Click **Test connection** where the form has one (database connections and authentication integrations): NocoDB resolves the references against the vault and tests with the values it gets back. An AI provider resolves them the first time it is used. 6. Save. The copy button next to **Reference** copies what you typed, and **Enter value directly** switches the field back to a typed credential. A PostgreSQL connection's password field switched to a vault reference, with the vault's secret names suggested Without the add-on, **Use a vault** carries the **Add-on** badge and opens the add-on dialog instead: Use a vault with the Add-on badge, under a PostgreSQL connection's Username and Password, on a Business plan Available as an Enterprise add-on, opened from Use a vault ### How a reference is written Each part is written either after a dot or inside brackets and quotes: * A part made only of letters, digits, `_` and `$`, not starting with a digit, can follow a dot: `secrets.awsProd`, `.password`. * Anything else goes in brackets and quotes: `["nocodb/prod/db/creds"]`. AWS secret names usually contain `/`, so they are almost always bracketed. The vault part is the vault's **reference name**, which is always letters and digits, so it never needs brackets. It must match the name exactly, including case: two vaults cannot differ only in case, but `awsprod` does not find `awsProd`. A field nested deeper inside a JSON secret adds another part, for example `secrets.awsProd["nocodb/app"].db.password`. What goes in the secret part depends on the provider: | Provider | The secret part is | A field after it | | --------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | | AWS Secrets Manager | the secret's name, or its full ARN for a secret in another account | required for a key/value secret, absent for a plain-text one | | HashiCorp Vault | the secret's path under the KV v2 mount, for example `prod/db` | required: a KV v2 secret is always a JSON document | | Azure Key Vault | the secret's name | none | | Google Secret Manager | the secret's name, or `projects//secrets/` for another project. Add `/versions/` to pin a version | none | | CyberArk Conjur | the variable's identifier, for example `data/db/password` | none | If the vault part names a vault that is not available to you, the box says so straight away: "No vault named 'x' is available to you." If it names a vault you can see but are not allowed to use, it says "You are not allowed to use the vault 'x'. Ask a workspace owner for access, or enter the credential directly." What is stored is a structured value, not the text you typed. There is no `{{ }}` template syntax, and a reference always replaces the whole field, so you cannot combine a literal prefix with a secret. Anything typed into a plain credential field, including `secrets.awsProd[…]` or `{{ secrets.… }}` text, is stored as the literal value. Always use **Use a vault**. ### Per-environment overrides A NocoDB AI provider or authentication integration can hold a different credential per environment. An override's credential field can be a reference too, to the same vault or another one, and the same rules apply: only the credential fields, and only vaults you are allowed to use. Database connections have no per-environment overrides. An OpenAI integration's API key backed by a vault, on the Production environment tab ### In a script A NocoDB script can put an integration's field into a request it sends, with a `{{.}}` placeholder. If that integration holds a vault reference in any field, even one the script does not use, the person running the script must be allowed to use the vault, exactly as if they were saving the reference. Otherwise the request fails with the message a save would give (see [A reference is rejected when I save the connection](/docs/product/integrations/vaults/troubleshooting#a-reference-is-rejected-when-i-save-the-connection)) and the secret is never read. An **Editor** the vault's setting does not include gets a clearer message instead: "This integration uses a vault secret, which editors can't use. Ask a workspace creator or owner." Have a Workspace Creator or Owner who may use the vault run the script. ## Naming a field inside the secret Vault providers store two kinds of secret, and the kind decides whether a reference names a field. * **AWS Secrets Manager** key/value secrets and every **HashiCorp Vault** KV v2 secret hold a JSON document with several fields, so a reference has to say which field it means. Naming the secret is not enough on its own. * **Azure Key Vault**, **Google Secret Manager** and **CyberArk Conjur** secrets hold one value, so a reference names the secret and must **not** add a field. For an AWS secret named `nocodb/prod/db/creds` holding `username` and `password`, the connection's **Username** field references its `username` field and the **Password** field references its `password` field. For Azure, Google or Conjur, store the username and the password as two secrets and reference each on its own. If a reference names such a secret without naming a field inside it, for example `secrets.awsProd["nocodb/prod/db/creds"]` on its own, resolving it fails with: > The referenced secret holds a JSON document. The reference must name a field inside it. (vault 'awsProd') For **Azure**, **Google** and **Conjur**, the form ignores a field written after the secret and says so: "This provider stores one value per secret, so the key path is ignored." For a **plain-text** AWS secret, a field after it is an error, and so is one sent through the API to a single-value secret that is not JSON text. Resolving it fails with: > The referenced secret holds a plain string, so the reference must not name a field inside it. (vault 'awsProd') Field names are suggested only for AWS Secrets Manager vaults, only to people allowed to use the vault, and only for a secret the provider itself listed. Typing a guessed secret id gets no suggestions, so the box cannot be used to find out whether a secret exists or what it holds. Values are never suggested or shown. ## What gets stored Saving stores the **reference only**: the vault's reference name, the secret's id, and the path to the field. NocoDB never writes the credential itself to its metadata database. That holds when you save, and when an integration later saves its own state (sync cursors, refreshed tokens): the stored reference is kept and only the value is replaced in memory. When a connection opens, NocoDB resolves the reference against the vault and uses the value to build that one connection. The resolved value is kept only in the server's memory, for at most five minutes, so a busy connection does not call the secrets manager on every open; it never appears in an API response, in a log, or anywhere in the UI, at any role. A credential rotated in your secrets manager is therefore picked up within about five minutes, with nothing to change in NocoDB. Updating the vault's own credentials, changing its scope or disconnecting it clears the cache immediately. ## What a non-owner sees Below **Workspace Owner**, a NocoDB vault reference is shown with its secret id masked: `secrets.awsProd["********"].password`. The vault name and the field are visible, the secret id is not, because an AWS ARN carries the account id. This applies to every integration type, to per-environment overrides, and to the project-scoped view of an integration. Saving the integration without retyping the reference keeps the stored secret id, and **Test connection** on a database connection being edited tests against the stored id too. ## Anyone using the project A project member never sees the resolved credential, whatever their project role. Project roles carry no vault permission, and there is no vault surface inside a project. ## Related * [Enterprise Vaults overview](/docs/product/integrations/vaults) * Provider setup: [HashiCorp Vault](/docs/product/integrations/vaults/hashicorp-vault) · [AWS Secrets Manager](/docs/product/integrations/vaults/aws-secrets-manager) · [Azure Key Vault](/docs/product/integrations/vaults/azure-key-vault) · [Google Secret Manager](/docs/product/integrations/vaults/google-secret-manager) · [CyberArk Conjur](/docs/product/integrations/vaults/cyberark-conjur) * [Vaults troubleshooting](/docs/product/integrations/vaults/troubleshooting) --- ## Related pages - [Connect AWS Secrets Manager](https://nocodb.com/docs/product/integrations/vaults/aws-secrets-manager.md): Connect AWS Secrets Manager to NocoDB as an Enterprise vault: create an IAM policy, an IAM user and an access key, then reference secrets from your integrations. - [Connect HashiCorp Vault](https://nocodb.com/docs/product/integrations/vaults/hashicorp-vault.md): Connect HashiCorp Vault to NocoDB as an Enterprise vault: write a policy, create an AppRole, then read secrets from a KV v2 mount in your integrations. - [Connect Azure Key Vault](https://nocodb.com/docs/product/integrations/vaults/azure-key-vault.md): Connect Azure Key Vault to NocoDB as an Enterprise vault: register an Entra ID application, give it read access to the Key Vault, then reference secrets from your integrations. - [Connect Google Secret Manager](https://nocodb.com/docs/product/integrations/vaults/google-secret-manager.md): Connect Google Secret Manager to NocoDB as an Enterprise vault: create a service account with secret access, add its key, then reference secrets from your integrations. - [Connect CyberArk Conjur](https://nocodb.com/docs/product/integrations/vaults/cyberark-conjur.md): Connect CyberArk Conjur to NocoDB as an Enterprise vault: load a policy with a host and variables, then reference the variables from your integrations with the host API key. - [Vaults Troubleshooting](https://nocodb.com/docs/product/integrations/vaults/troubleshooting.md): What NocoDB Enterprise Vaults error messages mean and how to fix them: failed vault tests, references that fail at connection time or on save, and refused name, scope and disconnect changes.