# Providers > Choose and configure the storage backends SecretSpec uses for secrets A provider is a storage backend from which SecretSpec reads secrets and, when supported, writes them. Providers let one `secretspec.toml` describe the secrets an application needs without requiring every environment to use the same secret store. For example, a developer can use the system keyring, CI can supply environment variables, and production can use a shared password manager or cloud secret manager. The secret definitions stay the same; only their provider configuration changes. ## Provider specifications Anywhere SecretSpec accepts a provider, you can use one of three forms: * A provider name, such as `keyring` or `env`. * A provider URI, such as `dotenv://.env.local` or `onepassword://Production`. The URI configures a particular instance of the provider. * A provider alias, such as `prod_vault`, defined in project or user configuration. Aliases are useful when a URI is shared by several secrets or should have a meaningful, store-independent name. **secretspec.toml** ```toml [providers] prod_vault = "onepassword://Production" [profiles.production] DATABASE_URL = { description = "Production database", providers = ["prod_vault"] } ``` ## Available providers | Provider | Storage backend | Read | Write | Encrypted at rest | TPM-backed keys | | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- | ------ | -------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | [keyring](/providers/keyring/) | [macOS Keychain](https://support.apple.com/guide/security/keychain-data-protection-secb0694df1a/web), [Windows Credential Manager](https://learn.microsoft.com/windows/win32/secauthn/credentials-management), or [Linux Secret Service](https://gnome.pages.gitlab.gnome.org/libsecret/) | ✓ | ✓ | ✓ | — | | [kdbx](/providers/kdbx/) (0.17+) | KeePass KDBX file (requires the `kdbx` build feature) | ✓ | KDBX 4 | ✓ | — | | [dotenv](/providers/dotenv/) | A `.env` file | ✓ | ✓ | ✗ | — | | [file](/providers/file/) (0.19+) | One plaintext byte file per secret (arbitrary bytes in 0.21+) | ✓ | ✓ | ✗ | — | | [env](/providers/env/) | Current process environment | ✓ | ✗ | ✗ | — | | [ejson](/providers/ejson/) (0.20+) | EJSON encrypted file (requires the `ejson` build feature and EJSON CLI) | ✓ | ✗ | ✓ | — | | [null](/providers/null/) (0.19+) | No storage; uses a manifest default, ephemeral generation, or an ephemeral run prompt | ✗ | ✗ | N/A | — | | [systemd-credential](/providers/systemd-credential/) (0.17+) | Credentials passed to the current systemd service (arbitrary bytes in 0.21+) | ✓ | ✗ | Depends on the unit’s credential source | [Via systemd-creds](https://www.freedesktop.org/software/systemd/man/latest/systemd-creds.html) | | [fly](/providers/fly/) (0.20+) | Fly.io application secrets through `flyctl` | ✗ | ✓ | ✓ | — | | [cloudflare](/providers/cloudflare/) (0.20+) | Cloudflare account-level Secrets Store through its REST API | ✗ | ✓ | ✓ | — | | [pass](/providers/pass/) | Unix `pass` password store | ✓ | ✓ | ✓ | [Via GnuPG](https://gnupg.org/blog/20210315-using-tpm-with-gnupg-2.3.html) | | [gopass](/providers/gopass/) (0.15+) | `gopass` password store (git-synced, GPG-encrypted) | ✓ | ✓ | ✓ | [Via GnuPG](https://gnupg.org/blog/20210315-using-tpm-with-gnupg-2.3.html) | | [protonpass](/providers/protonpass/) | Proton Pass | ✓ | ✓ | ✓ | — | | [passbolt](/providers/passbolt/) (0.19+) | Self-hosted Passbolt through `go-passbolt-cli` | ✓ | ✓ | ✓ | — | | [onepassword](/providers/onepassword/) | 1Password | ✓ | ✓ | ✓ | — | | [lastpass](/providers/lastpass/) | LastPass | ✓ | ✓ | ✓ | — | | [dashlane](/providers/dashlane/) (0.18+) | Dashlane, through the `dcli` CLI | ✓ | ✗ | ✓ | — | | [keeper](/providers/keeper/) (0.18+) | Keeper Secrets Manager (requires the `keeper` build feature) | ✓ | ✓ | ✓ | — | | [doppler](/providers/doppler/) (0.21+) | Doppler over its REST API (included by default; `doppler` feature for custom builds) | ✓ | ✓ | ✓ | — | | [gcsm](/providers/gcsm/) | Google Cloud Secret Manager (requires the `gcsm` build feature) | ✓ | ✓ | ✓ | — | | [awssm](/providers/awssm/) | AWS Secrets Manager, including `SecretBinary` (0.21+; requires the `awssm` build feature) | ✓ | ✓ | ✓ | — | | [awsps](/providers/awsps/) (0.18+) | AWS Systems Manager Parameter Store (requires the `awsps` build feature in 0.18+) | ✓ | ✓ | ✓ (`SecureString`) | — | | [scaleway](/providers/scaleway/) (0.17+) | Scaleway Secret Manager (requires the `scaleway` build feature) | ✓ | ✓ | ✓ | — | | [setec](/providers/setec/) (0.21+) | Tailscale Setec (included by default; `setec` feature for custom builds) | ✓ | ✓ | ✓ | Depends on server key configuration | | [vault](/providers/vault/) | HashiCorp Vault (requires the `vault` build feature) | ✓ | ✓ | ✓ | — | | [openbao](/providers/openbao/) (0.17+) | OpenBao (requires the `openbao` build feature; 0.16 uses `openbao://` through `vault`) | ✓ | ✓ | ✓ | — | | [bw](/providers/bw/) (0.18+) | Bitwarden Password Manager via the `bw` CLI (requires the `bw` build feature) | ✓ | ✓ | ✓ | — | | [bws](/providers/bws/) | Bitwarden Secrets Manager (official `bws` CLI in SecretSpec 0.17+; requires the `bws` build feature) | ✓ | ✓ | ✓ | — | | [akv](/providers/akv/) | Azure Key Vault (requires the `akv` build feature) | ✓ | ✓ | ✓ | — | | [aac](/providers/aac/) (0.20+) | Azure App Configuration, including Key Vault-reference resolution (included by default; `aac` feature for custom builds) | ✓ | ✓ | ✓ | — | | [infisical](/providers/infisical/) (0.16+) | Infisical (requires the `infisical` build feature) | ✓ | ✓ | ✓ | — | | [age](/providers/age/) (0.17+) | An age-encrypted file (requires the `age` build feature) | ✓ | ✓ | ✓ | — | | [sops](/providers/sops/) (0.17+) | SOPS-encrypted files (requires the `sops` build feature and SOPS CLI) | ✓ | ✓ | ✓ | Depends on the configured SOPS key service | | [kubernetes](/providers/kubernetes/) (0.20+) | Kubernetes ConfigMaps and Secrets (requires the `kubernetes` build feature) | ✓ | ✓ | [Secrets can be encrypted at rest](https://kubernetes.io/docs/tasks/administer-cluster/encrypt-data/#ensure-all-secrets-are-encrypted) | — | “TPM-backed keys” means the local key used by the provider can be protected by a [TPM 2.0](https://trustedcomputinggroup.org/resource/tpm-library-specification/) through the provider path SecretSpec uses. Pass and Gopass inherit this capability from GnuPG when its encryption key is moved to the TPM. systemd credentials inherit it from [systemd-creds](https://www.freedesktop.org/software/systemd/man/latest/systemd-creds.html), which seals encrypted credentials to the TPM2 by default when the host has one. [libsecret has an optional TPM2-enabled file backend](https://gnome.pages.gitlab.gnome.org/libsecret/libsecret-tpm2.html), but SecretSpec’s Linux keyring transport uses the Secret Service D-Bus API rather than that file backend. macOS Keychain uses Apple’s Secure Enclave rather than a TPM, and [Windows Vault credentials are not protected by Credential Guard](https://learn.microsoft.com/windows/security/identity-protection/credential-guard/how-it-works). An em dash means SecretSpec has no documented TPM integration for that provider; it does not describe other hardware security used internally by the provider service. Each provider page starts with a minimal working example, then covers setup, project configuration, storage conventions, existing provider-native secrets, and CI/CD where applicable. ## Configure the default provider Run the interactive configuration command to select the user-global provider SecretSpec uses when a secret has no provider-specific configuration. SecretSpec 0.17+ provides an explicit `global` namespace; the legacy spelling without it remains supported: ```bash $ secretspec config global init # 0.17+ ``` SecretSpec 0.17+ can persist the provider and profile non-interactively: ```bash $ secretspec config global init --provider env --profile default ``` The resulting user configuration contains a default provider: **\~/.config/secretspec/config.toml** ```toml [defaults] provider = "keyring" profile = "development" # Optional default profile ``` Use `--provider` for a one-off override, or `SECRETSPEC_PROVIDER` for commands in the current shell or CI job: ```bash # Route every secret in this command to a project .env file. $ secretspec run --provider dotenv -- npm start # Route every secret in subsequent commands to existing environment variables. $ export SECRETSPEC_PROVIDER=env $ secretspec check ``` `SECRETSPEC_PROVIDER` is a whole-resolution override: it replaces every per-secret fallback chain. Integrations such as devenv should only export it when the user explicitly configures a whole-resolution provider override. When consuming a JSON or SDK resolution, do not feed its top-level `provider` display label back into `SECRETSPEC_PROVIDER`; mixed per-secret routes cannot be represented by one provider string. Only export `SECRETSPEC_PROVIDER` when the user explicitly selected a whole-resolution override. Per-secret `source_provider` remains the authoritative provenance. A provider URI can configure the selected backend more precisely: ```bash # Select a specific 1Password vault. $ secretspec run --provider "onepassword://Development" -- npm start # Select a specific dotenv file. $ secretspec run --provider "dotenv:/home/user/work/.env" -- npm test ``` ## Configure a project default provider chain (0.21+) **New in version 0.21** Use project `[defaults].providers` when every profile should use the same provider chain unless a profile or secret overrides it. The chain can name a user-global alias, allowing each developer to supply personal provider-native coordinates while the committed manifest stays the same: **secretspec.toml** ```toml [defaults] providers = ["developer"] [profiles.staging] DATABASE_PASSWORD = { description = "Personal staging database password" } ``` **\~/.config/secretspec/config.toml** ```toml [defaults.providers.developer] uri = "awsps://developer@us-east-1" ref = { item = "/{project}/{profile}/developers/alice/{key}" } ``` The alias’s existing `{project}`, `{profile}`, and `{key}` placeholders expand in the project that selects it. Only `alice` is user-specific. Do not also declare `developer` in the project’s `[providers]` table, because a project alias with the same name takes precedence over the user-global alias. ## Configure provider aliases Provider aliases can be declared at either project or user scope: * Define project aliases in the top-level `[providers]` table in `secretspec.toml`. Commit these aliases so team members and CI use the same mapping. * Define user aliases in `[defaults.providers]` in `~/.config/secretspec/config.toml`. Use these for personal mappings that should apply across projects. If both scopes define the same alias, the project alias takes precedence. **secretspec.toml** ```toml [providers] prod_vault = "onepassword://Production" shared_vault = "onepassword://Shared" local = "keyring://" [profiles.production] DATABASE_URL = { description = "Production database", providers = ["prod_vault", "local"] } SENTRY_DSN = { description = "Error reporting", providers = ["shared_vault", "local"] } ``` Provider lists may combine aliases, provider names, and inline provider URIs: **secretspec.toml** ```toml [profiles.production] DATABASE_URL = { description = "Production database", providers = ["onepassword://Production", "keyring"] } ``` ### Alias ref templates **New in version 0.19** A leaf alias can map the logical `{project}`, `{profile}`, and `{key}` into its provider’s native coordinates. This lets every link in a fallback chain—and each side of an import—use a different address: **secretspec.toml** ```toml [providers] remote = { uri = "onepassword://Production", ref = { item = "{project}-{profile}", field = "{key}" } } local = { uri = "dotenv://.env", ref = { item = "{key}" } } [profiles.production] API_KEY = { description = "API key", providers = ["remote", "local"] } ``` Use per-secret `refs = { alias = { item = "..." } }` for exceptions. See [Secret References](/concepts/references/#different-coordinates-per-provider-019) for precedence, import-only source aliases, and cached-route restrictions. Use the CLI to manage user-level aliases: ```bash # SecretSpec 0.17+ $ secretspec config global provider add prod_vault "onepassword://Production" $ secretspec config global provider list $ secretspec config global provider remove prod_vault ``` These commands modify only `~/.config/secretspec/config.toml`. Edit the top-level `[providers]` table directly to change project aliases. ## Provider credentials **New in version 0.15** Some providers need credentials before they can retrieve secrets. Examples include an access token for Bitwarden Secrets Manager, a Vault token or AppRole credentials, a 1Password service account token, and Azure service-principal credentials. An alias can load these credentials from another provider. This avoids storing long-lived provider credentials in a shell profile or CI variable when a secure store is available. The [provider credential reference](/reference/provider-credentials/) lists every accepted semantic name, its environment fallbacks, and the SecretSpec version that introduced it. ### Use the convention address In an alias’s `credentials` table, map each semantic credential name to the provider that stores it: **secretspec.toml** ```toml [providers] keyring = "keyring://" # Read the access token from keyring before connecting to Bitwarden. bws = { uri = "bws://a9230ec4-5507-4870-b8b5-b3f500587e4c", credentials = { access_token = "keyring" } } ``` A string value such as `"keyring"` is a provider specification. SecretSpec reads the credential from that provider at the conventional `{project}/{profile}/{credential}` address for the active project and profile. ### Use an explicit address Use a table with `provider` and `ref` when the credential already exists at a specific provider-native address: **secretspec.toml** ```toml [providers.vault_prod] uri = "vault://secret/myapp?auth=approle" credentials = { role_id = { provider = "onepassword", ref = { vault = "Infra", item = "vault-approle", field = "role_id" } }, secret_id = { provider = "onepassword", ref = { vault = "Infra", item = "vault-approle", field = "secret_id" } } } ``` The `ref` table uses the same provider-native coordinates as a secret [`ref`](/reference/configuration/#secret-references). ### Store provider credentials Use `config provider login` to prompt for every credential declared by an alias and write it to the configured source: ```bash $ secretspec config provider login bws Enter access_token for provider 'bws' (source: keyring): **** ✓ stored access_token in keyring at smoke/default/access_token ``` You can also create a user-level alias with a convention-address credential source from the CLI: ```bash $ secretspec config global provider add bws "bws://project-uuid" --credential access_token=keyring # 0.17+ $ secretspec config provider login bws ``` Provider credentials follow these rules: * **Configured credentials are authoritative.** When an alias declares a credential, SecretSpec reads its configured source. Providers may still use their conventional environment variables when no explicit credential is supplied. * **Credential bytes are preserved (0.21+).** Resolution keeps each credential as bytes. Interfaces that require text validate UTF-8 when consuming it; validation errors never select an environment fallback. Unix CLI environments accept non-UTF-8 bytes but cannot contain NUL bytes. A configured credential that resolves to an empty value is an error rather than a fall through to the environment. * **Credentials remain internal.** SecretSpec passes a retrieved credential to the destination provider in memory. It does not export the credential or include it in the environment of a process started by `secretspec run`. * **Credential chains are one hop.** A source provider cannot require provider credentials of its own. SecretSpec validates this before accessing the provider, preventing dependency cycles. * **Convention addresses are profile-specific.** A string source uses the active project and profile. Use a `ref` source when multiple projects or profiles should share one provider credential. * **Names are provider-specific.** The catalog above is exhaustive. Unsupported names are rejected before any source is read. * **External providers negotiate names (0.21+).** An out-of-tree endpoint asks for the URI-specific credentials it needs at runtime. Its alias does not need a `credentials` table: SecretSpec can load requested values from a provider-private operating-system keyring namespace, and `config provider login` discovers and stores them. A configured mapping remains useful as an explicit source override and is read only if the endpoint requests its name. * **A URI may not carry a credential (0.19+).** A provider URI with a password (`scheme://user:PASSWORD@host`) is rejected, as is a service account token in the `onepassword+token://` userinfo. A URI is committed to `secretspec.toml`, echoed into shell history, and printed by CI, so a credential written there is already disclosed. Use a provider credential or the provider’s environment variable instead. ## Next steps * Learn how [Provider fallback](/concepts/providers/fallback/) selects and orders sources. * Cache slow remote routes and diagnose remaining latency with [Provider caching](/concepts/providers/caching/) (0.17+). * Review the URI and authentication details for an individual provider in the [Providers](/providers/keyring/) section. * Learn how [Profiles](/concepts/profiles/) apply provider defaults to an environment. * Learn how [Secret references](/concepts/references/) separate provider selection from provider-native addresses. ## Transient failures **New in version 0.22** SecretSpec retries recognized temporary failures against the same provider before trying a fallback or using an eligible cached value. The default is three total attempts with exponential backoff: 250 ms before the second attempt and 500 ms before the third. A server’s retry hint replaces the backoff, with a maximum wait of ten seconds per delay. HTTP providers recognize throttling (`429`) and temporary service failures (`500`, `502`, `503`, `504`), along with temporary transport failures. CLI providers use conservative signatures in failed-command diagnostics. Authentication failures, missing secrets, invalid configuration, malformed output, and unknown errors are returned immediately. Successful secret values never influence classification. Batch providers retain their optimized listing or bulk read. BWS retries its listing request, so a temporary failure does not immediately fail every secret in the profile. Vault and OpenBao retry inside the authenticated session without repeating AppRole login for a failed read. Mutations require an explicit replay-safety guarantee. The shared wrapper retries Doppler value-setting operations; it does not replay other providers’ writes, deletes, or expiring writes. Reads and authentication probes preceding a write can retry independently. SDK-native retry owners retain their own safety rules. AWS, Google Cloud Secret Manager, and Azure Key Vault receive the configured attempt budget and exponential backoff settings rather than an additional outer retry loop. A retry budget is not a request timeout or a total operation deadline. Retries stop for external-provider interaction, cancellation, and deadline errors. Configure the [user retry policy](/reference/configuration/#provider-retry-policy) or [override it in Rust](/sdk/rust/#provider-retry-policy). Setting one total attempt disables SecretSpec-controlled retries. Independently installed CLIs may have their own internal retries that this setting cannot control.