infisical/docs/sdks/languages/python.mdx

---
title: "Infisical Python SDK"
sidebarTitle: "Python"
icon: "python"
---

If you're working with Python, the official [infisical-python](https://github.com/Infisical/sdk/edit/main/crates/infisical-py) package is the easiest way to fetch and work with secrets for your application.

-   [PyPi Package](https://pypi.org/project/infisical-python/)
-   [Github Repository](https://github.com/Infisical/sdk/edit/main/crates/infisical-py)

## Basic Usage

```py
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.

<Warning>
	We do not recommend hardcoding your [Machine Identity Tokens](/platform/identities/overview). Setting it as an environment variable would be best.
</Warning>

## Installation

Run `pip` to add `infisical-python` to your project

```console
$ pip install infisical-python
```

Note: You need Python 3.7+.

## Configuration

Import the SDK and create a client instance with your [Machine Identity](/api-reference/overview/authentication).

```py
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

<ParamField query="options" type="object">
    <Expandable title="properties">
        <ParamField query="client_id" type="string" deprecated optional>
            Your Infisical Client ID.

            **This field is deprecated and will be removed in future versions.** Please use the `auth` field instead.
        </ParamField>
        <ParamField query="client_secret" type="string" deprecated optional>
            Your Infisical Client Secret.

          **This field is deprecated and will be removed in future versions.** Please use the `auth` field instead.
        </ParamField>
        <ParamField query="access_token" type="string" deprecated optional>
            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.
        </ParamField>

        <ParamField query="cache_ttl" type="number" default="300" optional>
            Time-to-live (in seconds) for refreshing cached secrets.
            If manually set to 0, caching will be disabled, this is not recommended.
        </ParamField>


        <ParamField
          query="site_url"
          type="string"
          default="https://app.infisical.com"
          optional
        >
          Your self-hosted absolute site URL including the protocol (e.g. `https://app.infisical.com`)
        </ParamField>

        <ParamField query="auth" type="AuthenticationOptions">
          The authentication object to use for the client. This is required unless you're using environment variables.
      </ParamField>
    </Expandable>

</ParamField>

### 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**
```python3
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
<Info>
  Please note that this authentication method will only work if you're running your application on Google Cloud Platform.
  Please [read more](/documentation/platform/identities/gcp-auth) about this authentication method.
</Info>

**Using environment variables**
- `INFISICAL_GCP_AUTH_IDENTITY_ID` - Your Infisical Machine Identity ID.

**Using the SDK directly**
```py
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**
```py
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
<Info>
  Please note that this authentication method will only work if you're running your application on AWS.
  Please [read more](/documentation/platform/identities/aws-auth) about this authentication method.
</Info>

**Using environment variables**
- `INFISICAL_AWS_IAM_AUTH_IDENTITY_ID` - Your Infisical Machine Identity ID.

**Using the SDK directly**
```py
from infisical_client import ClientSettings, InfisicalClient, AuthenticationOptions, AWSIamAuthMethod

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

#### Azure Auth
<Info>
  Please note that this authentication method will only work if you're running your application on Azure.
  Please [read more](/documentation/platform/identities/azure-auth) about this authentication method.
</Info>

**Using environment variables**
- `INFISICAL_AZURE_AUTH_IDENTITY_ID` - Your Infisical Machine Identity ID.

**Using the SDK directly**
```python
from infisical_client import InfisicalClient, ClientSettings, AuthenticationOptions, AzureAuthMethod

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


#### Kubernetes Auth
<Info>
  Please note that this authentication method will only work if you're running your application on Kubernetes.
  Please [read more](/documentation/platform/identities/kubernetes-auth) about this authentication method.
</Info>

**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**
```python
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)

```py
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

<ParamField query="Parameters" type="object">
    <Expandable title="properties">
        <ParamField query="environment" type="string" required>
            The slug name (dev, prod, etc) of the environment from where secrets should be fetched from.
        </ParamField>
          <ParamField query="project_id" type="string" required>
            The project ID where the secret lives in. 
        </ParamField>

         <ParamField query="path" type="string" optional>
            The path from where secrets should be fetched from.
        </ParamField>

        <ParamField query="attach_to_process_env" type="boolean" default="false" optional>
            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"]`.
        </ParamField>

        <ParamField query="recursive" type="boolean" default="false" optional>
            Whether or not to fetch secrets recursively from the specified path. Please note that there's a 20-depth limit for recursive fetching.
        </ParamField>

        <ParamField query="expand_secret_references" type="boolean" default="true" optional>
            Whether or not to expand secret references in the fetched secrets. Read about [secret reference](/documentation/platform/secret-reference)
        </ParamField>

        <ParamField query="include_imports" type="boolean" default="false" optional>
             Whether or not to include imported secrets from the current path. Read about [secret import](/documentation/platform/secret-reference)
        </ParamField>
    </Expandable>

</ParamField>

### client.getSecret(options)

```py
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

<ParamField query="Parameters" type="object" optional>
	<Expandable title="properties">
		<ParamField query="secret_name" type="string" required>
			The key of the secret to retrieve
		</ParamField>
		<ParamField query="environment" type="string" required>
			The slug name (dev, prod, etc) of the environment from where secrets should be fetched from.
		</ParamField>
		<ParamField query="project_id" type="string" required>
			The project ID where the secret lives in.
		</ParamField>
		<ParamField query="path" type="string" optional>
			The path from where secret should be fetched from.
		</ParamField>
		<ParamField query="type" type="string" optional>
			The type of the secret. Valid options are "shared" or "personal". If not specified, the default value is "personal".
		</ParamField>
		<ParamField query="include_imports" type="boolean" default="false" optional>
			Whether or not to include imported secrets from the current path. Read about [secret import](/documentation/platform/secret-reference)
		</ParamField>
	</Expandable>
</ParamField>

### client.createSecret(options)

```py
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

<ParamField query="Parameters" type="object" optional>
	<Expandable title="properties">
		<ParamField query="secret_name" type="string" required>
			The key of the secret to create.
		</ParamField>
		<ParamField query="secret_value" type="string" required>
			The value of the secret.
		</ParamField>
		<ParamField query="project_id" type="string" required>
			The project ID where the secret lives in.
		</ParamField>
		<ParamField query="environment" type="string" required>
			The slug name (dev, prod, etc) of the environment from where secrets should be fetched from.
		</ParamField>
		<ParamField query="path" type="string" optional>
			The path from where secret should be created.
		</ParamField>
		<ParamField query="type" type="string" optional>
			The type of the secret. Valid options are "shared" or "personal". If not specified, the default value is "shared".
		</ParamField>
	</Expandable>
</ParamField>

### client.updateSecret(options)

```py
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

<ParamField query="Parameters" type="object" optional>
	<Expandable title="properties">
		<ParamField query="secret_name" type="string" required>
			The key of the secret to update.
		</ParamField>
		<ParamField query="secret_value" type="string" required>
			The new value of the secret.
		</ParamField>
		<ParamField query="project_id" type="string" required>
			The project ID where the secret lives in.
		</ParamField>
		<ParamField query="environment" type="string" required>
			The slug name (dev, prod, etc) of the environment from where secrets should be fetched from.
		</ParamField>
		<ParamField query="path" type="string" optional>
			The path from where secret should be updated.
		</ParamField>
		<ParamField query="type" type="string" optional>
			The type of the secret. Valid options are "shared" or "personal". If not specified, the default value is "shared".
		</ParamField>
	</Expandable>
</ParamField>

### client.deleteSecret(options)

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

Delete a secret in Infisical.

#### Parameters

<ParamField query="Parameters" type="object" optional>
	<Expandable title="properties">
		<ParamField query="secret_name" type="string">
			The key of the secret to update.
		</ParamField>
		<ParamField query="project_id" type="string" required>
			The project ID where the secret lives in.
		</ParamField>
		<ParamField query="environment" type="string" required>
			The slug name (dev, prod, etc) of the environment from where secrets should be fetched from.
		</ParamField>
		<ParamField query="path" type="string" optional>
			The path from where secret should be deleted.
		</ParamField>
		<ParamField query="type" type="string" optional>
			The type of the secret. Valid options are "shared" or "personal". If not specified, the default value is "shared".
		</ParamField>
	</Expandable>
</ParamField>

## Cryptography

### Create a symmetric key

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

```py
key = client.createSymmetricKey()
```

#### Returns (string)

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

### Encrypt symmetric

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

encryptedData = client.encryptSymmetric(encryptOptions)
```

#### Parameters

<ParamField query="Parameters" type="object" required>
	<Expandable title="properties">
		<ParamField query="plaintext" type="string">
			The plaintext you want to encrypt.
		</ParamField>
		<ParamField query="key" type="string" required>
			The symmetric key to use for encryption.
		</ParamField>
	</Expandable>
</ParamField>

#### 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

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

decryptedString = client.decryptSymmetric(decryptOptions)


```

#### Parameters

<ParamField query="Parameters" type="object" required>
	<Expandable title="properties">
		<ParamField query="ciphertext" type="string">
			The ciphertext you want to decrypt.
		</ParamField>
		<ParamField query="key" type="string" required>
			The symmetric key to use for encryption.
		</ParamField>
		<ParamField query="iv" type="string" required>
			The initialization vector to use for decryption.
		</ParamField>
		<ParamField query="tag" type="string" required>
			The authentication tag to use for decryption.
		</ParamField>
	</Expandable>
</ParamField>

#### Returns (string)

`plaintext` (string): The decrypted plaintext.