Reference Format

We use the URL syntax to describe references to a secret store.

{vault://<vault-backend|entity>/<secret-id>[/<secret-key][/][?query][#version]}

Protocol/Scheme

{vault://<vault-backend|entity>/<secret-id>[/<secret-key]}
 ^^^^^

The vault in the URL is used as an identifier for Kong. We use this to reference a vault.

Host/Path

{vault://<vault-prefix>/<secret-id>[/<secret-key]}
         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The host and path of the URL defines the following:

Vault Prefix

The prefix for a vault can be either the name of the backend or the name of vault entity that you created.

Examples:

{vault://env/<secret-id>[/<secret-key]}
         ^^^

or using a vault entity

{vault://my-env-vault/<secret-id>[/<secret-key]}
         ^^^^^^^^^^^^

Secret ID

The secret-id is used as an identifier for a secret stored in a vault. The vault may return either a string value (a single secret) or multiple related secrets like username and password as a secret object.

Secret Key

The secret-key is used to identify the secret within the secret-id object.

If secret key ends with /, then it is not considered as a Secret Key but as a part of Secret Id. The difference between Secret Key and Secret Id is that only the Secret Id is sent to vault API, and the Secret Key is only used when processing

Query

Query arguments are used to denote configuration options in a key=value format to the Vault Prefix

Version

{vault://<vault-backend|entity>/<secret-id>[/<secret-key][/][?query][#version]}
                                                                     ^^^^^^^^

The version, specified as the fragment of the Vault URL, identifies the version number of the secret stored in a vault backend. Applies to any vault backend that supports versioning.