Infisical Python SDK

If you’re working with Python, the official infisical-python package is the easiest way to fetch and work with secrets for your application.

• PyPi Package
• Github Repository

Basic Usage

from flask import Flask
from infisical_client import ClientSettings, InfisicalClient, GetSecretOptions, AuthenticationOptions, UniversalAuthMethod

app = Flask(__name__)

client = InfisicalClient(ClientSettings(
    auth=AuthenticationOptions(
      universal_auth=UniversalAuthMethod(
        client_id="CLIENT_ID",
        client_secret="CLIENT_SECRET",
      )
    )
))

@app.route("/")
def hello_world():
    # access value

    name = client.getSecret(options=GetSecretOptions(
       environment="dev",
       project_id="PROJECT_ID",
       secret_name="NAME"
    ))

    return f"Hello! My name is: {name.secret_value}"

This example demonstrates how to use the Infisical Python SDK with a Flask application. The application retrieves a secret named “NAME” and responds to requests with a greeting that includes the secret value.

We do not recommend hardcoding your Machine Identity Tokens. Setting it as an environment variable would be best.

Installation

Run pip to add infisical-python to your project

$ pip install infisical-python

Note: You need Python 3.7+.

Configuration

Import the SDK and create a client instance with your Machine Identity.

from infisical_client import ClientSettings, InfisicalClient, AuthenticationOptions, UniversalAuthMethod

client = InfisicalClient(ClientSettings(
    auth=AuthenticationOptions(
      universal_auth=UniversalAuthMethod(
        client_id="CLIENT_ID",
        client_secret="CLIENT_SECRET",
      )
    )
))

Parameters

options · object

Show properties

client_id · string · deprecated

Your Infisical Client ID.

This field is deprecated and will be removed in future versions. Please use the auth field instead.

client_secret · string · deprecated

Your Infisical Client Secret.

This field is deprecated and will be removed in future versions. Please use the auth field instead.

access_token · string · deprecated

If you want to directly pass an access token obtained from the authentication endpoints, you can do so.

This field is deprecated and will be removed in future versions. Please use the auth field instead.

cache_ttl · number · default: "300"

Time-to-live (in seconds) for refreshing cached secrets. If manually set to 0, caching will be disabled, this is not recommended.

site_url · string · default: "https://app.infisical.com"

Your self-hosted absolute site URL including the protocol (e.g. https://app.infisical.com)

auth · AuthenticationOptions

The authentication object to use for the client. This is required unless you’re using environment variables.

Authentication

The SDK supports a variety of authentication methods. The most common authentication method is Universal Auth, which uses a client ID and client secret to authenticate.

Universal Auth

Using environment variables

• INFISICAL_UNIVERSAL_AUTH_CLIENT_ID - Your machine identity client ID.
• INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET - Your machine identity client secret.

Using the SDK directly

from infisical_client import ClientSettings, InfisicalClient, AuthenticationOptions, UniversalAuthMethod

client = InfisicalClient(ClientSettings(
    auth=AuthenticationOptions(
      universal_auth=UniversalAuthMethod(
        client_id="CLIENT_ID",
        client_secret="CLIENT_SECRET",
      )
    )
))

GCP ID Token Auth

Please note that this authentication method will only work if you’re running your application on Google Cloud Platform. Please read more about this authentication method.

Using environment variables

• INFISICAL_GCP_AUTH_IDENTITY_ID - Your Infisical Machine Identity ID.

Using the SDK directly

from infisical_client import ClientSettings, InfisicalClient, AuthenticationOptions, GCPIDTokenAuthMethod

client = InfisicalClient(ClientSettings(
    auth=AuthenticationOptions(
        gcp_id_token=GCPIDTokenAuthMethod(
            identity_id="MACHINE_IDENTITY_ID",
        )
    )
))

GCP IAM Auth

Using environment variables

• INFISICAL_GCP_IAM_AUTH_IDENTITY_ID - Your Infisical Machine Identity ID.
• INFISICAL_GCP_IAM_SERVICE_ACCOUNT_KEY_FILE_PATH - The path to your GCP service account key file.

Using the SDK directly

from infisical_client import ClientSettings, InfisicalClient, AuthenticationOptions, GCPIamAuthMethod


client = InfisicalClient(ClientSettings(
    auth=AuthenticationOptions(
        gcp_iam=GCPIamAuthMethod(
            identity_id="MACHINE_IDENTITY_ID",
            service_account_key_file_path="./path/to/service_account_key.json"
        )
    )
))

AWS IAM Auth

Please note that this authentication method will only work if you’re running your application on AWS. Please read more about this authentication method.

Using environment variables

• INFISICAL_AWS_IAM_AUTH_IDENTITY_ID - Your Infisical Machine Identity ID.

Using the SDK directly

from infisical_client import ClientSettings, InfisicalClient, AuthenticationOptions, AWSIamAuthMethod

client = InfisicalClient(ClientSettings(
    auth=AuthenticationOptions(
        aws_iam=AWSIamAuthMethod(identity_id="MACHINE_IDENTITY_ID")
    )
))

Azure Auth

Please note that this authentication method will only work if you’re running your application on Azure. Please read more about this authentication method.

Using environment variables

• INFISICAL_AZURE_AUTH_IDENTITY_ID - Your Infisical Machine Identity ID.

Using the SDK directly

from infisical_client import InfisicalClient, ClientSettings, AuthenticationOptions, AzureAuthMethod

kubernetes_client = InfisicalClient(ClientSettings(
    auth=AuthenticationOptions(
        azure=AzureAuthMethod(
            identity_id="YOUR_IDENTITY_ID",
        )
    )
))

Kubernetes Auth

Please note that this authentication method will only work if you’re running your application on Kubernetes. Please read more about this authentication method.

Using environment variables

• INFISICAL_KUBERNETES_IDENTITY_ID - Your Infisical Machine Identity ID.
• INFISICAL_KUBERNETES_SERVICE_ACCOUNT_TOKEN_PATH_ENV_NAME - The environment variable name that contains the path to the service account token. This is optional and will default to /var/run/secrets/kubernetes.io/serviceaccount/token.

Using the SDK directly

from infisical_client import InfisicalClient, ClientSettings, AuthenticationOptions, KubernetesAuthMethod

kubernetes_client = InfisicalClient(ClientSettings(
    auth=AuthenticationOptions(
        kubernetes=KubernetesAuthMethod(
            identity_id="YOUR_IDENTITY_ID",
            service_account_token_path="/var/run/secrets/kubernetes.io/serviceaccount/token" # Optional
        )
    )
))

Caching

To reduce the number of API requests, the SDK temporarily stores secrets it retrieves. By default, a secret remains cached for 5 minutes after it’s first fetched. Each time it’s fetched again, this 5-minute timer resets. You can adjust this caching duration by setting the “cache_ttl” option when creating the client.

Working with Secrets

client.listSecrets(options)

client.listSecrets(options=ListSecretsOptions(
    environment="dev",
    project_id="PROJECT_ID"
))

Retrieve all secrets within the Infisical project and environment that client is connected to

Parameters

Parameters · object

Show properties

environment · string · required

The slug name (dev, prod, etc) of the environment from where secrets should be fetched from.

project_id · string · required

The project ID where the secret lives in.

path · string

The path from where secrets should be fetched from.

attach_to_process_env · boolean · default: "false"

Whether or not to set the fetched secrets to the process environment. If true, you can access the secrets like so process.env["SECRET_NAME"].

recursive · boolean · default: "false"

Whether or not to fetch secrets recursively from the specified path. Please note that there’s a 20-depth limit for recursive fetching.

expand_secret_references · boolean · default: "true"

Whether or not to expand secret references in the fetched secrets. Read about secret reference

include_imports · boolean · default: "false"

Whether or not to include imported secrets from the current path. Read about secret import

client.getSecret(options)

secret = client.getSecret(options=GetSecretOptions(
    environment="dev",
    project_id="PROJECT_ID",
    secret_name="API_KEY"
))
value = secret.secret_value # get its value

By default, getSecret() fetches and returns a shared secret. If not found, it returns a personal secret.

Parameters

Parameters · object

Show properties

secret_name · string · required

The key of the secret to retrieve

environment · string · required

The slug name (dev, prod, etc) of the environment from where secrets should be fetched from.

project_id · string · required

The project ID where the secret lives in.

path · string

The path from where secret should be fetched from.

type · string

The type of the secret. Valid options are “shared” or “personal”. If not specified, the default value is “personal”.

include_imports · boolean · default: "false"

Whether or not to include imported secrets from the current path. Read about secret import

client.createSecret(options)

api_key = client.createSecret(options=CreateSecretOptions(
    secret_name="API_KEY",
    secret_value="Some API Key",
    environment="dev",
    project_id="PROJECT_ID"
))

Create a new secret in Infisical.

Parameters

Parameters · object

Show properties

secret_name · string · required

The key of the secret to create.

secret_value · string · required

The value of the secret.

project_id · string · required

The project ID where the secret lives in.

environment · string · required

The slug name (dev, prod, etc) of the environment from where secrets should be fetched from.

path · string

The path from where secret should be created.

type · string

The type of the secret. Valid options are “shared” or “personal”. If not specified, the default value is “shared”.

client.updateSecret(options)

client.updateSecret(options=UpdateSecretOptions(
    secret_name="API_KEY",
    secret_value="NEW_VALUE",
    environment="dev",
    project_id="PROJECT_ID"
))

Update an existing secret in Infisical.

Parameters

Parameters · object

Show properties

secret_name · string · required

The key of the secret to update.

secret_value · string · required

The new value of the secret.

project_id · string · required

The project ID where the secret lives in.

environment · string · required

The slug name (dev, prod, etc) of the environment from where secrets should be fetched from.

path · string

The path from where secret should be updated.

type · string

The type of the secret. Valid options are “shared” or “personal”. If not specified, the default value is “shared”.

client.deleteSecret(options)

client.deleteSecret(options=DeleteSecretOptions(
    environment="dev",
    project_id="PROJECT_ID",
    secret_name="API_KEY"
))

Delete a secret in Infisical.

Parameters

Parameters · object

Show properties

secret_name · string

The key of the secret to update.

project_id · string · required

The project ID where the secret lives in.

environment · string · required

The slug name (dev, prod, etc) of the environment from where secrets should be fetched from.

path · string

The path from where secret should be deleted.

type · string

The type of the secret. Valid options are “shared” or “personal”. If not specified, the default value is “shared”.

Cryptography

Create a symmetric key

Create a base64-encoded, 256-bit symmetric key to be used for encryption/decryption.

key = client.createSymmetricKey()

Returns (string)

key (string): A base64-encoded, 256-bit symmetric key, that can be used for encryption/decryption purposes.

Encrypt symmetric

encryptOptions = EncryptSymmetricOptions(
    key=key,
    plaintext="Infisical is awesome!"
)

encryptedData = client.encryptSymmetric(encryptOptions)

Parameters

Parameters · object · required

Show properties

plaintext · string

The plaintext you want to encrypt.

key · string · required

The symmetric key to use for encryption.

Returns (object)

tag (string): A base64-encoded, 128-bit authentication tag. iv (string): A base64-encoded, 96-bit initialization vector. ciphertext (string): A base64-encoded, encrypted ciphertext.

Decrypt symmetric

decryptOptions = DecryptSymmetricOptions(
    ciphertext=encryptedData.ciphertext,
    iv=encryptedData.iv,
    tag=encryptedData.tag,
    key=key
)

decryptedString = client.decryptSymmetric(decryptOptions)

Parameters

Parameters · object · required

Show properties

ciphertext · string

The ciphertext you want to decrypt.

key · string · required

The symmetric key to use for encryption.

iv · string · required

The initialization vector to use for decryption.

tag · string · required

The authentication tag to use for decryption.

Returns (string)

plaintext (string): The decrypted plaintext.