Connect to a secret

Sign in to your secret store from your terminal or your application, then store, read, and delete values, and give each application a token of its own. For every other command, see the OpenBao command reference.

Before you begin

You need:

• A secret in the Running state. To create one, see Get started with E2E Secrets Management.
• The store’s token and domain, from the credentials page the account owner’s email links to. The domain is also under Domain on the secret’s Info tab in MyAccount; the token is only on the credentials page.
• The bao command-line tool, installed with the OpenBao installation guide.

Set the address and token

To point bao at your store, set its address and token. Replace <domain> with the store’s domain, and <token> with its token. The domain looks like openbao-<number>.e2enetworks.net, where the number is your secret’s id. You reach the store over HTTPS on the standard port, 443, so the address needs no port number.

export VAULT_ADDR="https://<domain>"
export VAULT_TOKEN="<token>"

Sign in with the token, then check it:

bao login $VAULT_TOKEN
bao token lookup

bao token lookup prints the token’s details, including its policies and how long it has left.

To check the store itself, run:

bao status

bao status prints the store’s state, including whether it is sealed. Keep its output for support if the store stops answering.

Store and read values

A secrets engine stores, generates, or encrypts data, and each one is turned on at a path of its own. The key-value engine, KV version 2, is the one most people use for passwords and keys. It also keeps earlier versions of each value. For the other engines, see OpenBao’s secrets engines.

To see which engines are turned on, list them:

bao secrets list

If secret/ is not in the list, turn on the key-value engine at that path:

bao secrets enable -path=secret kv-v2

Then work with your values:

# Store a value, or add a new version of it
bao kv put secret/app key="value123"

# Read it
bao kv get secret/app

# Update it
bao kv put secret/app key="updated-value"

# List everything stored under secret/
bao kv list secret/

# Delete the latest version; earlier versions stay
bao kv delete secret/app

# Delete every version and the record of them, for good
bao kv metadata delete secret/app

To store several values at once, give each as its own key=value pair in one bao kv put command. You can also keep them in a JSON file and pass the file with @:

bao kv put secret/app db_user="<user>" db_password="<password>"
bao kv put secret/app @app.json

Rotate the values stored under each path, such as database passwords, regularly. Each bao kv put stores the new value as the latest version.

Create a token for each application

Give each application its own token, so you can revoke one without touching the others. A token you create lasts 87,600 hours (10 years) unless you revoke it. To make one that expires sooner, set its lifetime:

bao token create -ttl=24h

bao prints the new token under token. Give that value to the application.

To check a token, pass it to bao token lookup. To stop it working, revoke it:

bao token lookup <token>
bao token revoke <token>

What your token can do

The token E2E emails you is a renewable token with the policy default, not a root token. In your store, that policy lets it do everything on every path. It can turn on secrets engines and auth methods, store and read values, write policies, and create and revoke tokens.

E2E keeps the store’s root token and recovery keys, and unseals the store for you, including after a restart. Your token cannot seal, unseal, or step down the store, rotate or rekey its encryption keys, or generate a root or recovery token. It also cannot read key or high-availability status, manage the store’s storage cluster, profile it, or read its raw storage.

You can read the policies default, admin-policy, and user-policy, and you can write policies of your own. To learn how policies are written, see OpenBao’s policies.

Connect from an application

Any client library built for the Vault API works with your store. Each needs the store’s address and a token. These libraries are widely used:

Language	Library
Python	hvac
Java	vault-java-driver
Go	the Vault API client, github.com/hashicorp/vault/api
Node.js	node-vault

In Python, install hvac:

pip install hvac

Connect to the store. The client reads the address and token from the two variables in Set the address and token. On the machine the application runs on, set both, but give the token variable the application’s own token, not the token E2E emailed you. That is the token you created for it in Create a token for each application.

import os
import hvac

client = hvac.Client(
    url=os.environ["VAULT_ADDR"],
    token=os.environ["VAULT_TOKEN"],
)
print("Authenticated:", client.is_authenticated())

The script prints Authenticated: True.

If the key-value engine is not turned on yet, turn on KV version 2 at secret, the path these bao commands use:

client.sys.enable_secrets_engine(
    backend_type="kv",
    path="secret",
    options={"version": "2"},
)

Then store a value and read it back:

client.secrets.kv.v2.create_or_update_secret(
    mount_point="secret",
    path="app",
    secret={"db_password": "<password>"},
)

data = client.secrets.kv.v2.read_secret_version(
    mount_point="secret",
    path="app",
)
print("Secret:", data["data"]["data"])

The mount point in the example, secret, is the path where the key-value engine is turned on. The script prints the value you stored.

To update the value, write it again, with the new password in place of <new-password>. The store keeps the new value as the latest version. The second call deletes the latest version, as bao kv delete does:

client.secrets.kv.v2.create_or_update_secret(
    mount_point="secret",
    path="app",
    secret={"db_password": "<new-password>"},
)

client.secrets.kv.v2.delete_latest_version_of_secret(
    mount_point="secret",
    path="app",
)

For every call hvac offers, see the hvac documentation.

Your applications can now read their values from the store with tokens of their own. For help when the store does not answer or a command is refused, see Troubleshooting E2E Secrets Management.