vaultriever

Retrieve secrets in an ARN-like way from different vaults seamlessly, compatible with pydantic-settings — no custom field types, just str fields plus a reusable mixin.

It's particularly useful for projects that need to support multiple vaults, or for libraries that want to avoid forcing a specific vault on their users.

Secret Resource Identifier (SRI)

Secrets are addressed with a 4-part string:

provider:qualifier:secret_name:secret_key

Installation

pip install vaultriever[aws]         # AWS Secrets Manager
pip install vaultriever[databricks]  # Databricks (not needed on a Databricks runtime)
pip install vaultriever[azure]       # Azure Key Vault
pip install vaultriever[gcp]         # GCP Secret Manager

Usage

With pydantic-settings

from pydantic import Field, SecretStr
from pydantic_settings import BaseSettings
from vaultriever import SecretSRIMixin


class OpenAISettings(SecretSRIMixin, BaseSettings):
    openai_api_key: str | SecretStr = Field(
        default='aws:us-east-1:my-secret:OPENAI_API_KEY',
        description='OpenAI API key; SRI or literal.',
    )


settings = OpenAISettings()
settings.openai_api_key                     # SecretStr('**********') — masked
settings.openai_api_key.get_secret_value()  # the resolved secret

Behavior:

• str / SecretStr values that look like an SRI (and reference a registered provider) are resolved and wrapped in SecretStr, so they stay masked in repr() and logs.
• Everything else passes through unchanged — literals, URLs, non-string values.
• Validated values are also exported to os.environ under the field name for downstream usage by default. This writes resolved secrets in plaintext to the process environment; see the opt out instructions and disable it per model:

from typing import ClassVar


class MySettings(SecretSRIMixin, BaseSettings):
    enable_env_export: ClassVar[bool] = False

    api_key: str | SecretStr

Standalone

from vaultriever import is_sri, resolve_secret

is_sri('aws:us-east-1:my-secret:API_KEY')          # True
resolve_secret('aws:us-east-1:my-secret:API_KEY')  # 'sk-...'

Custom providers

from vaultriever import SecretProviderRegistry
from vaultriever.sri import SecretProperties


class MyVaultProvider:
    name = 'myvault'

    def get_secret_value(self, props: SecretProperties) -> str:
        ...


SecretProviderRegistry.register(MyVaultProvider())
# Now 'myvault:qualifier:name:key' SRIs resolve through it.

Providers

AWS Secrets Manager

• Credentials come from the AWS SDK default chain (env vars, profile, IAM role).
• The region is required and taken from the SRI.
• If the secret's SecretString is a JSON object, secret_key is required and selects a key from it. If it's plaintext (or JSON that isn't an object), omit secret_key (aws:region:name:) to get the whole SecretString back — providing a key for a plaintext secret, or omitting it for a JSON-object secret, raises an error.
• Secret payloads are cached per (secret_name, region) for the process lifetime; call AWSSecretProvider.clear_cache() after a rotation.

Databricks

• On a Databricks runtime, secrets are read via the native dbutils.
• Elsewhere, the databricks-sdk is used with default authentication, or with the CLI profile named by the SRI's qualifier component (databricks:staging:my-scope:MY_KEY).

Azure Key Vault

• Credentials come from DefaultAzureCredential (env vars, managed identity, Azure CLI, etc.).
• The qualifier is the vault name; the provider builds the vault URL as https://<vault_name>.vault.azure.net/.
• Secret values are cached per (vault_name, secret_name, version) for the process lifetime; call AzureSecretProvider.clear_cache() after a rotation.

GCP Secret Manager

• Credentials come from Application Default Credentials (ADC).
• The qualifier is the GCP project id; the provider builds the resource name projects/<project_id>/secrets/<secret_name>/versions/<version>.
• Secret values are cached per (project_id, secret_name, version) for the process lifetime; call GCPSecretProvider.clear_cache() after a rotation.

Development

uv sync --all-extras --dev
uv run pytest
uv run ruff check .
uv run mypy

Run uv run pre-commit install once so ruff format, ruff check --fix, and mypy run automatically on git commit — this is the same pre-commit config the CI lint job runs, so a clean local commit means CI lint will pass too.

Releases are published to PyPI by pushing a vX.Y.Z tag.

License

MIT