Backends

You can choose among different pluggable secret storage backends. You can set the backend using the --backend flag or the AWS_VAULT_BACKEND environment variable. Run aws-vault --help to see what your --backend flag supports.

The supported vaulting backends are:

Use the --backend flag or AWS_VAULT_BACKEND environment variable to specify a backend. Run aws-vault --help to see the backends available in your build and environment.

By default, aws-vault selects the first available backend for the platform: wincred on Windows, keychain on macOS, and secret-service on Linux when Secret Service is available. On Linux, automatic selection then falls back through kwallet, keyctl, pass, passage, and file. The 1Password, Proton Pass and oo7 backends are opt-in and are listed after file, so choose them explicitly with --backend or AWS_VAULT_BACKEND.

Keychain

If you’re looking to configure the amount of time between having to enter your Keychain password for each usage of a particular profile, you can do so through Keychain:

1. Open “Keychain Access”
2. Open the aws-vault keychain. If you do not have “aws-vault” in the sidebar of the Keychain app, then you can do “File -> Add Keychain” and select the aws-vault.keychain-db. This is typically created in Users/{USER}/Library/Keychains.
3. Right click on aws-vault keychain, and select “Change Settings for Keychain ‘aws-vault”
4. Update “Lock after X minutes of inactivity” to your desired value.
5. Hit save.

Touch ID

With --biometrics (or AWS_VAULT_BIOMETRICS=true), aws-vault uses Touch ID to unlock the aws-vault keychain. Touch ID is only requested when the keychain is locked: while it stays unlocked, commands run without prompting, including each credential_process call. How often you see Touch ID therefore follows the lock settings above, which you can also set from the command line:

# Lock after 15 minutes of inactivity and when the Mac sleeps
security set-keychain-settings -lut 900 aws-vault.keychain
security show-keychain-info aws-vault.keychain

The first time Touch ID is needed, aws-vault asks for the keychain password once in the terminal and stores it in your login keychain. credential_process can’t show that prompt, so do the first unlock from a terminal: lock the keychain with security lock-keychain aws-vault.keychain, then run any command, such as aws-vault list --biometrics.

If you use a separate session keychain (--session-keychain), each keychain is checked and unlocked separately.

oo7

oo7 is the Secret Service implementation GNOME is moving to. Its daemon speaks the standard D-Bus API, so the secret-service backend keeps working with it. The oo7 backend instead reads and writes oo7’s keyring file format directly, in a file of its own:

• no D-Bus session or keyring daemon is involved, so nothing has to pop up a prompt and it works over SSH and in headless sessions (AWS_VAULT_OO7_PASSPHRASE supplies the passphrase for scripts);
• the file lives at ~/.local/share/aws-vault/keyrings/default.keyring ($XDG_DATA_HOME is honoured, which also puts it in the right place inside a Flatpak), or wherever --oo7-keyring-path / AWS_VAULT_OO7_KEYRING_PATH points. It is kept out of ~/.local/share/keyrings/v1/ on purpose: oo7-daemon loads every keyring it finds there as a collection, and writes made through the daemon would bypass aws-vault’s lock;
• several aws-vault processes can share the file: writers take a lock on it and replace it atomically.

export AWS_VAULT_BACKEND=oo7
aws-vault add my-profile

Key source

The file is encrypted with a key derived from a secret selected by --oo7-key-source / AWS_VAULT_OO7_KEY_SOURCE:

A keyring created with one key source cannot be opened with the other; in auto mode the error says which source was tried and suggests setting OO7KeySource explicitly. That is the keyring library’s name for this setting: in aws-vault, set it with --oo7-key-source or AWS_VAULT_OO7_KEY_SOURCE.

Working with oo7-cli

oo7-cli can open the same file, which is handy for inspection or recovery. Leave out -s and it asks for the passphrase on the terminal:

oo7-cli -k ~/.local/share/aws-vault/keyrings/default.keyring list

Unlike the oo7 backend, oo7-cli may need a session D-Bus even when it only reads a file, so over SSH you may have to point DBUS_SESSION_BUS_ADDRESS at your session bus first.

To move existing credentials from another backend, use migrate-backend, for example aws-vault migrate-backend --from secret-service --to oo7.

Proton Pass

⚠️ Experimental. The proton-pass backend talks to an undocumented, internal Proton API and depends on a credential model that may change. Review the Terms of Service note below before using it for anything unattended.

The proton-pass backend stores each profile’s credentials as an item in a Proton Pass vault, reached directly over Proton’s HTTPS API. It does not shell out to the Proton Pass CLI at runtime — you only use the CLI once, to mint and scope the access token.

aws-vault authenticates with a Proton Pass Personal Access Token (PAT), a scoped, Proton-issued automation credential of the form pst_<token>::<key>. The whole string is the credential: the pst_<token> half is exchanged for a session, and the ::<key> half is the key that decrypts the vault.

1. Mint and scope a PAT

Install the Proton Pass CLI and log in, then create a token and grant it access. A dedicated vault keeps aws-vault’s items isolated:

# Optional: a dedicated vault for aws-vault items
pass-cli vault create --name aws-vault

# Mint the PAT — the pst_…::… value is printed ONCE; store it now
# --expiration is one of: 1d, 1w, 1m, 3m, 6m, 1y
pass-cli pat create --name aws-vault --expiration 3m

# Find the token's <ID>
pass-cli pat list

# Grant access (see the grant-scope table below for which role/scope you need)
pass-cli pat access grant --pat-id <ID> --vault-name aws-vault --role editor

# ...or, for least privilege, scope to one already-existing profile item.
# The item title is "<prefix>/<profile>" (default prefix "aws-vault"):
pass-cli pat access grant --pat-id <ID> --vault-name aws-vault \
  --item-title aws-vault/my-profile --role viewer

The grant determines what aws-vault can do, and Proton’s role model (viewer < editor < manager) governs the rest:

The add-needs-a-vault-level-grant constraint is the one that bites in practice; the read/update/delete rows follow Proton’s role model. The simplest setup is a single vault-level editor grant, which covers every command. Use a per-item token only when the profile already exists and you want least privilege (for example a read-only viewer token on a CI runner that only runs exec).

2. Find the Share ID

A grant creates a recipient share for the PAT with its own Share ID. That ID — not the vault owner’s — is what aws-vault needs:

pass-cli pat access list-access --pat-id <ID>

3. Configure aws-vault

export PROTON_PASS_PERSONAL_ACCESS_TOKEN='pst_xxxx::KEY'

aws-vault --backend=proton-pass \
  --proton-pass-share-id=<SHARE_ID> \
  add my-profile

Set AWS_VAULT_BACKEND=proton-pass and AWS_VAULT_PROTON_PASS_SHARE_ID=<SHARE_ID> to avoid repeating the flags. If PROTON_PASS_PERSONAL_ACCESS_TOKEN is unset, aws-vault prompts for the token. The token is never accepted as a command-line flag, which would leak it into the process list and shell history.

The backend also reads the Proton Pass CLI’s own PROTON_PASS_SHARE_ID and PROTON_PASS_API_BASE variables as a fallback, so an existing CLI environment works unchanged. The aws-vault-specific AWS_VAULT_PROTON_PASS_* variables (and their flags) take precedence when both are set.

Session caching and rate limits

The first command exchanges your PAT for a Proton session and caches that session in your OS keychain (macOS Keychain, Secret Service, KWallet, or Windows Credential Manager), under a dedicated aws-vault-proton-pass-session entry. Subsequent commands reuse it, so a normal add → list → exec sequence performs a single login. The cache entry is keyed to your token, so rotating the PAT invalidates it automatically; a session that Proton has expired or revoked is detected and the PAT re-exchanged on the next call.

This caching is what keeps the backend under Proton’s login rate limit. Without it, every command re-runs the full exchange, and a few commands in quick succession trip HTTP 429 / code 2028 "Too many recent logins". On a host with no OS keychain available (for example a headless Linux box with no Secret Service), the session cannot be cached and every operation re-exchanges the PAT — space your commands out, or expect the occasional rate-limit error.

--proton-pass-timeout (default 30s, env AWS_VAULT_PROTON_PASS_TIMEOUT) bounds each operation, including the several HTTP calls a single command makes.

Errors are reported plainly: a rate-limit response tells you to wait and retry; a rejected PAT tells you to mint or re-grant a token; and a demand for human verification (CAPTCHA / 2FA), which this client cannot satisfy, asks you to re-authenticate with the Proton Pass app or CLI to clear it.

Terms of Service

Proton’s Terms of Service (Section 2, “Authorized use of the Services”) prohibit accessing the Services “through automated means (including but not limited to bots, scripts, or similar technologies)”. Interactive use — running aws-vault exec yourself, with you present — reads as an unofficial client acting on your behalf. Unattended or CI use is the gray area for that clause and is at your own risk. A PAT is the most clearly authorized automation credential Proton offers, but it does not exempt you from the automated-access clause. This is an engineering reading, not legal advice; get sign-off before relying on it for unattended access.