Skip to content

Python API

import seeqret

cn = psycopg.connect(..., password=seeqret.get('myapp:prod:DB_PASSWORD'))

seeqret.get() reads one secret from the local vault, decrypts it and returns its value. It is fast (thousands of lookups per second), so there is no need to cache the result.

Fetch secrets at the last possible moment

Call seeqret.get() where the secret is used, not in a settings module. A secret held in a module-level variable can end up in tracebacks, debug pages and logs:

DB_PASSWORD = seeqret.get('myapp:prod:DB_PASSWORD')       # BAD

cn = mydb.connect(..., password=seeqret.get('myapp:prod:DB_PASSWORD'))  # GOOD

Naming a secret

A secret is identified by app, env and key. You can name it the same way as on the command line (seeqret get myapp:prod:DB_PASSWORD), or pass the parts separately:

seeqret.get('myapp:prod:DB_PASSWORD')
seeqret.get('DB_PASSWORD', app='myapp', env='prod')    # same secret
Call Looks up
seeqret.get('myapp:prod:DB_PASSWORD') myapp:prod:DB_PASSWORD
seeqret.get(':prod:DB_PASSWORD') *:prod:DB_PASSWORD
seeqret.get('::DB_PASSWORD') *:*:DB_PASSWORD
seeqret.get('DB_PASSWORD') *:*:DB_PASSWORD

Empty parts mean *, as in filter strings. Use either the app:env:key form or the app=/env= arguments, not both.

The reference must match exactly one secret. * in a reference is a wildcard, so a reference like '::DB_PASSWORD' fails if the key exists in more than one app or environment.

Return value

The decrypted value, converted according to the secret's type: str secrets are returned as str, int secrets as int.

Errors

Exception Raised when
seeqret.SecretNotFound no secret matches
seeqret.AmbiguousSecret more than one secret matches
ValueError the reference is malformed or conflicts with app=/env=

The messages say what was looked up and how to find the secret, e.g.:

seeqret.storage.storage.SecretNotFound: No secret yerbu:dev:CRON_SECRET in vault C:\srv\seeqret\seeqrets.db.
See where 'CRON_SECRET' exists with: seeqret list "*:*:CRON_SECRET"
seeqret.storage.storage.AmbiguousSecret: 2 secrets match *:*:CRON_SECRET:
    yerbu:dev:CRON_SECRET
    yerbu:prod:CRON_SECRET
Name the app and env, e.g. seeqret.get('yerbu:dev:CRON_SECRET').

Neither message contains secret values.

SecretNotFound is a KeyError (and an IndexError, which older versions raised). AmbiguousSecret is a LookupError, and its matches attribute lists the matching app:env:key names. To handle both:

try:
    token = seeqret.get('myapp:prod:API_TOKEN')
except LookupError as err:
    sys.exit(str(err))

Which vault is used

On Windows, and whenever the SEEQRET environment variable is set, the vault is the directory SEEQRET points to (seeqret init sets it on Windows). Otherwise it is /srv/.seeqret.