Skip to main content

Python client for the SecretHub Secrets Management API

Project description

SecretHub Client for Python BETA

This repository provides a Python client for the SecretHub Secrets Management API.

SecretHub is a secrets management tool that works for every engineer and allows you to securely provision passwords and keys throughout your entire stack with just a few lines of code.

Table of Contents


To install the SecretHub package from PyPi, run the following command:

python -m pip install secrethub

The package supports Linux, Windows (32 and 64 bit) and MacOS. It is built for CPython versions 3.5 and above.

Make sure you have created a SecretHub account and set up a credential on your system before using the library. See the Credential section for more info.

Note that passphrase protected credentials are not supported by the Python client.


Before doing any calls to the library, you need to import the secrethub package and create a client:

import secrethub
client = secrethub.Client()

After you have your client, you can call the following methods:


Retrieve a secret value as a string.

secret = client.read_string("path/to/secret")


Retrieve a secret, including all its metadata.

secret ="path/to/secret");

The returned object is of the secrethub.SecretVersion type and it represents a version of a secret with the sensitive value stored in the data field. It provides the following fields:

  • secret_version_id
  • secret
  • version
  • data
  • created_at
  • status


Check if a secret exists at path.

secret_exists = client.exists("path/to/secret")

write(path, secret)

Write a secret value to a given path.

client.write("path/to/secret", "secret_value")


Delete the secret found at path.



Resolve a secret reference tag of the format secrethub://<path> and return the corresponding secret value. If ref is not a valid reference tag, it returns otherwise it returns ref unchanged.

resolved_ref = client.resolve("secrethub://path/to/secret")


Return a dictionary containing the OS environment with all secret references (secrethub://<path>) replaced by their corresponding secret values.


os.environ['MY_SECRET'] = 'secrethub://path/to/secret'
os.environ['OTHER_VARIABLE'] = 'some other value'

resolved_env = client.resolve_env()

# Prints all environment variables with any secret references resolved to their corresponding value
# {
#    'MY_SECRET': 'the value of the secret stored at path/to/secret',
#    'OTHER_VARIABLE': 'some other value'
# }


Adds the environment variables defined in the env dictionary to the environment of the process. If any of them are already present in the environment, they will be overwritten.

This method can be used together with resolve_env to resolve all environment variables with secret references and set them to their corresponding secret value. Note that we recommend you use client.resolve_env() for most cases, but if your code reads its configuration from the environment and cannot be adapted to use the result of client.resolve_env() directly you can use it together with export_env().


os.environ['MY_SECRET'] = 'secrethub://path/to/secret'


print("secret: " + os.environ['MY_SECRET']);
# Prints the value of the secret stored at path/to/secret.


Any error encountered by the SecretHub client will be thrown as a RuntimeError with the full error message as an associated string value.

except Exception as e:


To use the SecretHub Python client, you need to provide a credential for your SecretHub account. You can sign up for a free developer account here.

After signup, the credential is located at $HOME/.secrethub/credential by default. secrethub.Client() automatically uses this credential.

You can also provide a credential through the SECRETHUB_CREDENTIAL environment variable.

Getting Help

Come chat with us on Discord or email us at


This project is currently in beta and we'd love your feedback! Check out the issues and feel free suggest cool ideas, use cases, or improvements.

Because it's still in beta, you can expect to see some changes introduced. Pull requests are very welcome.

For support, send us a message on Discord or send an email to


Note that most of the code in this repository is automatically generated from the SecretHub XGO project, which wraps the secrethub-go client with cgo exported functions so it can be called form other languages, e.g. C, C#, Python, Ruby, NodeJS, and Java. To generate the code SWIG is used.

See the SecretHub XGO repository for more details.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release. See tutorial on generating distribution archives.

Built Distributions

secrethub-0.1.1-cp39-cp39-win_amd64.whl (9.7 MB view hashes)

Uploaded cp39

secrethub-0.1.1-cp39-cp39-win32.whl (9.4 MB view hashes)

Uploaded cp39

secrethub-0.1.1-cp38-cp38-win_amd64.whl (9.7 MB view hashes)

Uploaded cp38

secrethub-0.1.1-cp38-cp38-win32.whl (9.4 MB view hashes)

Uploaded cp38

secrethub-0.1.1-cp37-cp37m-win_amd64.whl (9.7 MB view hashes)

Uploaded cp37

secrethub-0.1.1-cp37-cp37m-win32.whl (9.4 MB view hashes)

Uploaded cp37

secrethub-0.1.1-cp36-cp36m-win_amd64.whl (9.7 MB view hashes)

Uploaded cp36

secrethub-0.1.1-cp36-cp36m-win32.whl (9.4 MB view hashes)

Uploaded cp36

secrethub-0.1.1-cp35-cp35m-win_amd64.whl (9.7 MB view hashes)

Uploaded cp35

secrethub-0.1.1-cp35-cp35m-win32.whl (9.4 MB view hashes)

Uploaded cp35

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page