> ## Documentation Index
> Fetch the complete documentation index at: https://infisical-groups-phase-3.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Infisical Python SDK

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

app = Flask(__name__)

client = InfisicalClient(ClientSettings(
    client_id="MACHINE_IDENTITY_CLIENT_ID",
    client_secret="MACHINE_IDENTITY_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

client = InfisicalClient(ClientSettings(
    client_id="MACHINE_IDENTITY_CLIENT_ID",
    client_secret="MACHINE_IDENTITY_CLIENT_SECRET",
))
```

#### Parameters

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

    <ParamField query="client_secret" type="string" optional>
      Your Infisical Client Secret.
    </ParamField>

    <ParamField query="access_token" type="string" optional>
      If you want to directly pass an access token obtained from the authentication endpoints, you can do so.
    </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>
  </Expandable>
</ParamField>

### 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="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.