credentials 0.4.1

Fetch secrets from either environment variables or Hashicorp's Vault

credentials: Fetch secrets from the environment or from Vault

Latest version License Build Status

API Documentation.

A twelve-factor app (as popularized by Heroku) would normally store any passwords or other secrets in environment variables. The alternative would be to include the passwords directly in the source code, which would make it much easier to accidentally reveal them to the world.

But once your application deployment becomes more complex, it's much easier to store passwords in a central, secure store such as Hashicorp's Vault or Square's Keywhiz.

Wherever you choose to store your secrets, this library is intended to provide a single, unified API:


By default, this will return the values of the EXAMPLE_USERNAME and EXAMPLE_PASSWORD environment variables.

Accessing Vault

To fetch the secrets from Vault, you will first need to set up the same things you would need to use the vault command line tool or the vault Ruby gem:

  • You need to set the VAULT_ADDR environment variable to the URL of your Vault server.
  • You can store your Vault token in either the environment variable VAULT_TOKEN or the file ~/.vault-token.

Let's assume you have the following secret stored in your vault:

vault write secret/example username=myuser password=mypass

To access it, you'll need to create a Secretfile in the directory from which you run your application:

# Comments are allowed.
EXAMPLE_USERNAME secret/example:username
EXAMPLE_PASSWORD secret/example:password

If you have per-environment secrets, you can interpolate environment variables into the path portion of the Secretfile using $VAR or ${VAR}:

PG_USERNAME postgresql/$VAULT_ENV/creds/readonly:username
PG_PASSWORD postgresql/$VAULT_ENV/creds/readonly:password

As before, you can access these secrets using:



Example code

See the examples directory for complete, working code.


The following features remain to be implemented:

  • Honor Vault TTLs.
  • Keywhiz support. The big obstacle here is that I can't get Keywhiz keystore stuff working correctly using curl.


Your feedback and contributions are welcome! Just file an issue or send a GitHub pull request.