Skip to content

Infisical is the open-source platform for securing secrets, certificates, access, and AI Agents.

38.1 KB
Raw Blame
---
title: "Infisical Python SDK"
sidebarTitle: "Python"
description: "Fetch and manage secrets in a Python application with the official Infisical Python SDK."
icon: "/images/sdks/languages/python.svg"
---

If you're working with Python, the official Infisical Python SDK package is the easiest way to fetch and work with secrets for your application. 

### Migrating to version 1.0.3 or above

We have recently rolled out our first stable version of the SDK, version `1.0.3` and above.

The 1.0.3 version comes with a few key changes that may change how you're using the SDK.
1. **Removal of `rest`**: The SDK no longer exposes the entire Infisical API. This was necessary as we have moved away from using an OpenAPI generator approach. We aim to add support for more API resources in the near future. If you have any specific requests, please [open an issue](https://github.com/Infisical/python-sdk-official/issues).

2. **New response types**: The 1.0.3 release uses return types that differ from the older versions. The new return types such as `BaseSecret`, are all exported from the Infisical SDK.

3. **Property renaming**: Some properties on the responses have been slightly renamed. An example of this would be that the `secret_key` property on the `get_secret_by_name()` method, that has been renamed to `secretKey`.

With this in mind, you're ready to upgrade your SDK version to `1.0.3` or above. 

You can refer to our [legacy documentation](https://github.com/Infisical/python-sdk-official/tree/9b0403938ee5ae599d42c5f1fdf9158671a15606?tab=readme-ov-file#infisical-python-sdk) if need be.

## Requirements

Python 3.7+

## Installation

```bash
pip install infisicalsdk
```

## Getting started

```python
from infisical_sdk import InfisicalSDKClient

# Initialize the client
client = InfisicalSDKClient(host="https://app.infisical.com")

# Authenticate (example using Universal Auth)
client.auth.universal_auth.login(
    client_id="<machine-identity-client-id>", 
    client_secret="<machine-identity-client-secret>"
)

# Use the SDK to interact with Infisical
secrets = client.secrets.list_secrets(project_id="<project-id>", environment_slug="dev", secret_path="/")
```

## InfisicalSDKClient parameters

The `InfisicalSDKClient` takes the following parameters, which are used as a global configuration for the lifetime of the SDK instance.

- **host** (`str`, _Optional_): The host URL for your Infisical instance. Defaults to `https://app.infisical.com`.
- **token** (`str`, _Optional_): Specify an authentication token to use for all requests. If provided, you won't need to call any of the `auth` methods. Defaults to `None`
- **cache_ttl** (`int`, _Optional_): The SDK has built-in client-side caching for secrets, greatly improving response times. By default, secrets are cached for 1 minute (60 seconds). You can disable caching by setting `cache_ttl` to `None`, or adjust the duration in seconds as needed.

```python
client = InfisicalSDKClient(
  host="https://app.infisical.com", # Defaults to https://app.infisical.com
  token="<optional-auth-token>", # If not set, use the client.auth() methods.
  cache_ttl = 300 # `None` to disable caching
)
```

## Core methods

The SDK methods are organized into the following high-level categories:

1. `auth`: Handles authentication methods.
2. `secrets`: Manages CRUD operations for secrets.
3. `dynamic_secrets`: Manages dynamic secrets and leases.
4. `kms`: Perform cryptographic operations with Infisical KMS.
5. `folders`: Manages folder-related operations.
6. `agent_vault`: Manages [Agent Vault](/documentation/platform/agent-vault/overview) sessions and proxies.

### `auth`

The `Auth` component provides methods for authentication:

#### Universal auth

```python
response = client.auth.universal_auth.login(
    client_id="<machine-identity-client-id>", 
    client_secret="<machine-identity-client-secret>"
)
```

#### AWS auth

```python
response = client.auth.aws_auth.login(identity_id="<machine-identity-id>")
```

#### OIDC auth

```python
response = client.auth.oidc_auth.login(
    identity_id="<oidc-identity-id>",
    jwt="<your-oidc-jwt-token>"
)
```

**Parameters:**
- `identity_id` (str): The ID of the OIDC identity configuration in Infisical.
- `jwt` (str): The OIDC JWT token obtained from your identity provider.

This authentication method is useful when integrating with OIDC-compliant identity providers like Okta, Auth0, or any service that issues OIDC tokens.

#### LDAP auth

```python
response = client.auth.ldap_auth.login(
    identity_id="<machine-identity-id>",
    username="<ldap-username>",
    password="<ldap-password>"
)
```

**Parameters:**
- `identity_id` (str): The ID of the LDAP identity configuration in Infisical.
- `username` (str): Your LDAP username.
- `password` (str): Your LDAP password.

<Info>
  Please note that this authentication method requires LDAP credentials. Please
  [read more](/documentation/platform/identities/ldap-auth/general) about this
  authentication method.
</Info>

#### Token auth

```python
response = client.auth.token_auth.login(token="<your-token>")
```

**Parameters:**
- `token` (str): The access token to authenticate with. This can be a [machine identity token](/documentation/platform/identities/token-auth) or a user access token.

### `secrets`

This sub-class handles operations related to secrets:

#### List secrets

```python
secrets = client.secrets.list_secrets(
    project_id="<project-id>",
    environment_slug="dev",
    secret_path="/",
    expand_secret_references=True, # Optional
    view_secret_value=True, # Optional 
    recursive=False, # Optional
    include_imports=True, # Optional
    tag_filters=[] # Optional
)
```

**Parameters:**
- `project_id` (str): The ID of your project.
- `project_slug` (str): The slug of your project.
- `environment_slug` (str): The environment in which to list secrets (e.g., "dev").
- `secret_path` (str): The path to the secrets.
- `expand_secret_references` (bool): Whether to expand secret references.
- `view_secret_value` (bool): Whether or not to include the secret value in the response. If set to false, the `secretValue` will be masked with `<hidden-by-infisical>`. Defaults to true.
- `recursive` (bool): Whether to list secrets recursively.
- `include_imports` (bool): Whether to include imported secrets.
- `tag_filters` (List[str]): Tags to filter secrets.

**Note:** Exactly one of `project_id` or `project_slug` is required. If both are provided, `project_id` takes precedence.

**Returns:**
- `ListSecretsResponse`: The response containing the list of secrets.

#### Create secret

```python
new_secret = client.secrets.create_secret_by_name(
    secret_name="NEW_SECRET",
    project_id="<project-id>",
    secret_path="/",
    environment_slug="dev",
    secret_value="secret_value",
    secret_comment="Optional comment",
    skip_multiline_encoding=False,
    secret_reminder_repeat_days=30,  # Optional
    secret_reminder_note="Remember to update this secret",  # Optional
    secret_metadata=[{"key": "metadata_key", "value": "metadata_value"}], # Optional
    tags_ids=["tag_id_1", "tag_id_2"] # Optional
)
```

**Parameters:**
- `secret_name` (str): The name of the secret.
- `project_id` (str): The ID of your project.
- `project_slug` (str): The slug of your project.
- `secret_path` (str): The path to the secret.
- `environment_slug` (str): The environment in which to create the secret.
- `secret_value` (str): The value of the secret.
- `secret_comment` (str, optional): A comment associated with the secret.
- `skip_multiline_encoding` (bool, optional): Whether to skip encoding for multiline secrets.
- `secret_reminder_repeat_days` (Union[float, int], optional): Number of days after which to repeat secret reminders.
- `secret_reminder_note` (str, optional): A note for the secret reminder.
- `secret_metadata` (List[Dict[str, Any]], optional): Metadata associated with the secret.
- `tags_ids` (List[str], optional): IDs of tags to associate with the secret.

**Note:** Exactly one of `project_id` or `project_slug` is required. If both are provided, `project_id` takes precedence.

**Returns:**
- `BaseSecret`: The response after creating the secret.

#### Update secret

```python
updated_secret = client.secrets.update_secret_by_name(
    current_secret_name="EXISTING_SECRET",
    project_id="<project-id>",
    project_slug="<project-slug>",
    secret_path="/",
    environment_slug="dev",
    secret_value="new_secret_value",
    secret_comment="Updated comment",  # Optional
    skip_multiline_encoding=False,
    secret_reminder_repeat_days=30,  # Optional
    secret_reminder_note="Updated reminder note",  # Optional
    new_secret_name="NEW_NAME",  # Optional
    secret_metadata=[{"key": "metadata_key", "value": "metadata_value"}], # Optional
    tags_ids=["tag_id_1", "tag_id_2"] # Optional
)
```

**Parameters:**
- `current_secret_name` (str): The current name of the secret.
- `project_id` (str): The ID of your project.
- `project_slug` (str): The slug of your project.
- `secret_path` (str): The path to the secret.
- `environment_slug` (str): The environment in which to update the secret.
- `secret_value` (str, optional): The new value of the secret.
- `secret_comment` (str, optional): An updated comment associated with the secret.
- `skip_multiline_encoding` (bool, optional): Whether to skip encoding for multiline secrets.
- `secret_reminder_repeat_days` (Union[float, int], optional): Updated number of days after which to repeat secret reminders.
- `secret_reminder_note` (str, optional): An updated note for the secret reminder.
- `new_secret_name` (str, optional): A new name for the secret.
- `secret_metadata` (List[Dict[str, Any]], optional): Metadata associated with the secret.
- `tags_ids` (List[str], optional): IDs of tags to associate with the secret.

**Note:** Exactly one of `project_id` or `project_slug` is required. If both are provided, `project_id` takes precedence.

**Returns:**
- `BaseSecret`: The response after updating the secret.

#### Get secret by name

```python
secret = client.secrets.get_secret_by_name(
    secret_name="EXISTING_SECRET",
    project_id="<project-id>",
    environment_slug="dev",
    secret_path="/",
    expand_secret_references=True, # Optional
    view_secret_value=True, # Optional
    include_imports=True, # Optional
    version=None # Optional
)
```

**Parameters:**
- `secret_name` (str): The name of the secret.
- `project_id` (str): The ID of your project.
- `project_slug` (str): The slug of your project.
- `environment_slug` (str): The environment in which to retrieve the secret.
- `secret_path` (str): The path to the secret.
- `expand_secret_references` (bool): Whether to expand secret references.
- `view_secret_value` (bool): Whether or not to include the secret value in the response. If set to false, the `secretValue` will be masked with `<hidden-by-infisical>`. Defaults to true.
- `include_imports` (bool): Whether to include imported secrets.
- `version` (str, optional): The version of the secret to retrieve. Fetches the latest by default.

**Note:** Exactly one of `project_id` or `project_slug` is required. If both are provided, `project_id` takes precedence.

**Returns:**
- `BaseSecret`: The response containing the secret.

#### Delete secret by name

```python
deleted_secret = client.secrets.delete_secret_by_name(
    secret_name="EXISTING_SECRET",
    project_id="<project-id>",
    environment_slug="dev",
    secret_path="/"
)
```

**Parameters:**
- `secret_name` (str): The name of the secret to delete.
- `project_id` (str): The ID of your project.
- `project_slug` (str): The slug of your project.
- `environment_slug` (str): The environment in which to delete the secret.
- `secret_path` (str): The path to the secret.

**Note:** Exactly one of `project_id` or `project_slug` is required. If both are provided, `project_id` takes precedence.

**Returns:**
- `BaseSecret`: The response after deleting the secret.

### `dynamic_secrets`

This sub-class handles operations related to dynamic secrets. Dynamic secrets generate credentials on-demand with automatic expiration. For more information, see the [Dynamic Secrets documentation](/documentation/platform/dynamic-secrets/overview).

#### Create dynamic secret

```python
from infisical_sdk import DynamicSecretProviders

dynamic_secret = client.dynamic_secrets.create(
    name="postgres-dev",
    provider_type=DynamicSecretProviders.SQL_DATABASE,
    inputs={
        "client": "postgres",
        "host": "localhost",
        "port": 5432,
        "database": "mydb",
        "username": "admin",
        "password": "admin-password",
        "creationStatement": "CREATE USER \"{{username}}\" WITH PASSWORD '{{password}}';",
        "revocationStatement": "DROP USER \"{{username}}\";"
    },
    default_ttl="1h",
    max_ttl="24h",
    project_slug="my-project",
    environment_slug="dev",
    path="/",
    metadata=[{"key": "team", "value": "backend"}]  # Optional
)
```

**Parameters:**
- `name` (str): The name of the dynamic secret.
- `provider_type` (Union[DynamicSecretProviders, str]): The provider type (e.g., `DynamicSecretProviders.SQL_DATABASE`).
- `inputs` (Dict[str, Any]): The provider-specific configuration inputs. See the [Dynamic Secrets API documentation](/api-reference/endpoints/dynamic-secrets/create) for provider-specific inputs.
- `default_ttl` (str): The default time to live for leases (e.g., "1h", "30m").
- `max_ttl` (str): The maximum time to live for leases (e.g., "24h").
- `project_slug` (str): The slug of your project.
- `environment_slug` (str): The environment in which to create the dynamic secret.
- `path` (str, optional): The path where the dynamic secret will be created. Defaults to "/".
- `metadata` (List[Dict[str, str]], optional): Optional list of metadata items with 'key' and 'value'.

**Returns:**
- `DynamicSecret`: The created dynamic secret.

#### Supported provider types

The `DynamicSecretProviders` enum includes the following providers:

| Provider | Enum Value |
| -------- | ---------- |
| AWS ElastiCache | `DynamicSecretProviders.AWS_ELASTICACHE` |
| AWS IAM | `DynamicSecretProviders.AWS_IAM` |
| Azure Entra ID | `DynamicSecretProviders.AZURE_ENTRA_ID` |
| Azure SQL Database | `DynamicSecretProviders.AZURE_SQL_DATABASE` |
| Cassandra | `DynamicSecretProviders.CASSANDRA` |
| Couchbase | `DynamicSecretProviders.COUCHBASE` |
| Elasticsearch | `DynamicSecretProviders.ELASTICSEARCH` |
| GCP IAM | `DynamicSecretProviders.GCP_IAM` |
| GitHub | `DynamicSecretProviders.GITHUB` |
| Kubernetes | `DynamicSecretProviders.KUBERNETES` |
| LDAP | `DynamicSecretProviders.LDAP` |
| MongoDB Atlas | `DynamicSecretProviders.MONGO_ATLAS` |
| MongoDB | `DynamicSecretProviders.MONGODB` |
| RabbitMQ | `DynamicSecretProviders.RABBITMQ` |
| Redis | `DynamicSecretProviders.REDIS` |
| SAP ASE | `DynamicSecretProviders.SAP_ASE` |
| SAP HANA | `DynamicSecretProviders.SAP_HANA` |
| Snowflake | `DynamicSecretProviders.SNOWFLAKE` |
| SQL Database | `DynamicSecretProviders.SQL_DATABASE` |
| TOTP | `DynamicSecretProviders.TOTP` |
| Vertica | `DynamicSecretProviders.VERTICA` |

#### Get dynamic secret by name

```python
dynamic_secret = client.dynamic_secrets.get_by_name(
    name="postgres-dev",
    project_slug="my-project",
    environment_slug="dev",
    path="/"
)
```

**Parameters:**
- `name` (str): The name of the dynamic secret.
- `project_slug` (str): The slug of your project.
- `environment_slug` (str): The environment in which to retrieve the dynamic secret.
- `path` (str, optional): The path to the dynamic secret. Defaults to "/".

**Returns:**
- `DynamicSecret`: The dynamic secret.

#### Update dynamic secret

```python
updated_secret = client.dynamic_secrets.update(
    name="postgres-dev",
    project_slug="my-project",
    environment_slug="dev",
    path="/",
    default_ttl="2h",  # Optional
    max_ttl="48h",  # Optional
    new_name="postgres-dev-updated",  # Optional
    inputs={"port": 5433},  # Optional - updated provider inputs
    metadata=[{"key": "team", "value": "platform"}],  # Optional
    username_template="dev-{{identity.name}}"  # Optional
)
```

**Parameters:**
- `name` (str): The current name of the dynamic secret.
- `project_slug` (str): The slug of your project.
- `environment_slug` (str): The environment in which to update the dynamic secret.
- `path` (str, optional): The path to the dynamic secret. Defaults to "/".
- `default_ttl` (str, optional): The new default time to live for leases.
- `max_ttl` (str, optional): The new maximum time to live for leases.
- `new_name` (str, optional): The new name for the dynamic secret.
- `inputs` (Dict[str, Any], optional): Updated provider-specific configuration inputs.
- `metadata` (List[Dict[str, str]], optional): Updated metadata list with 'key' and 'value' items.
- `username_template` (str, optional): The new username template for the dynamic secret.

**Returns:**
- `DynamicSecret`: The updated dynamic secret.

#### Delete dynamic secret

```python
deleted_secret = client.dynamic_secrets.delete(
    name="postgres-dev",
    project_slug="my-project",
    environment_slug="dev",
    path="/",
    is_forced=False  # Optional
)
```

**Parameters:**
- `name` (str): The name of the dynamic secret to delete.
- `project_slug` (str): The slug of your project.
- `environment_slug` (str): The environment in which to delete the dynamic secret.
- `path` (str, optional): The path to the dynamic secret. Defaults to "/".
- `is_forced` (bool, optional): A boolean flag to delete the dynamic secret from Infisical without trying to remove it from the external provider. Defaults to `False`.

**Returns:**
- `DynamicSecret`: The deleted dynamic secret.

### `dynamic_secrets.leases`

This sub-class handles operations related to dynamic secret leases. A lease represents a set of generated credentials with a specific TTL.

#### Create lease

Create a lease to generate credentials from a dynamic secret:

```python
lease_response = client.dynamic_secrets.leases.create(
    dynamic_secret_name="postgres-dev",
    project_slug="my-project",
    environment_slug="dev",
    path="/",
    ttl="30m"  # Optional
)

# Access the generated credentials
username = lease_response.data["DB_USERNAME"]
password = lease_response.data["DB_PASSWORD"]
lease_id = lease_response.lease.id
```

**Parameters:**
- `dynamic_secret_name` (str): The name of the dynamic secret to create a lease for.
- `project_slug` (str): The slug of your project.
- `environment_slug` (str): The environment in which to create the lease.
- `path` (str, optional): The path to the dynamic secret. Defaults to "/".
- `ttl` (str, optional): The time to live for the lease (e.g., "1h", "30m").

**Returns:**
- `CreateLeaseResponse`: Response containing:
  - `lease`: The lease object with ID, expiration, and metadata.
  - `dynamicSecret`: The associated dynamic secret.
  - `data`: The generated credentials. The structure depends on the dynamic secret provider.

#### Get lease

```python
lease = client.dynamic_secrets.leases.get(
    lease_id="<lease-id>",
    project_slug="my-project",
    environment_slug="dev",
    path="/"
)
```

**Parameters:**
- `lease_id` (str): The ID of the lease to retrieve.
- `project_slug` (str): The slug of your project.
- `environment_slug` (str): The environment in which to retrieve the lease.
- `path` (str, optional): The path to the dynamic secret. Defaults to "/".

**Returns:**
- `DynamicSecretLease`: The lease with dynamicSecret included.

#### Renew lease

Extend the TTL of an existing lease:

```python
renewed_lease = client.dynamic_secrets.leases.renew(
    lease_id="<lease-id>",
    project_slug="my-project",
    environment_slug="dev",
    path="/",
    ttl="2h"  # Optional - new TTL
)
```

**Parameters:**
- `lease_id` (str): The ID of the lease to renew.
- `project_slug` (str): The slug of your project.
- `environment_slug` (str): The environment in which to renew the lease.
- `path` (str, optional): The path to the dynamic secret. Defaults to "/".
- `ttl` (str, optional): The new time to live for the lease.

**Returns:**
- `DynamicSecretLease`: The renewed lease.

#### Revoke lease

Revoke a lease and its associated credentials:

```python
revoked_lease = client.dynamic_secrets.leases.revoke(
    lease_id="<lease-id>",
    project_slug="my-project",
    environment_slug="dev",
    path="/",
    is_forced=False  # Optional
)
```

**Parameters:**
- `lease_id` (str): The ID of the lease to revoke.
- `project_slug` (str): The slug of your project.
- `environment_slug` (str): The environment in which to revoke the lease.
- `path` (str, optional): The path to the dynamic secret. Defaults to "/".
- `is_forced` (bool, optional): A boolean flag to revoke the lease from Infisical without trying to remove it from the external provider. Defaults to `False`.

**Returns:**
- `DynamicSecretLease`: The revoked lease.

### `kms`

This sub-class handles KMS related operations:

#### List KMS keys

```python
kms_keys = client.kms.list_keys(
    project_id="<project-id>",
    offset=0, # Optional
    limit=100, # Optional
    order_by=KmsKeysOrderBy.NAME, # Optional
    order_direction=OrderDirection.ASC, # Optional
    search=None # Optional
)
```

**Parameters:**
- `project_id` (str): The ID of your project.
- `offset` (int, optional): The offset to paginate from.
- `limit` (int, optional): The page size for paginating.
- `order_by` (KmsKeysOrderBy, optional): The key property to order the list response by.
- `order_direction` (OrderDirection, optional): The direction to order the list response in.
- `search` (str, optional): The text value to filter key names by.

**Returns:**
- `ListKmsKeysResponse`: The response containing the list of KMS keys.

#### Get KMS key by ID

```python
kms_key = client.kms.get_key_by_id(
    key_id="<key-id>"
)
```

**Parameters:**
- `key_id` (str): The ID of the key to retrieve.

**Returns:**
- `KmsKey`: The specified key.

#### Get KMS key by name

```python
kms_key = client.kms.get_key_by_name(
    key_name="my-key",
    project_id="<project-id>"
)
```

**Parameters:**
- `key_name` (str): The name of the key to retrieve.
- `project_id` (str): The ID of your project.

**Returns:**
- `KmsKey`: The specified key.

#### Create KMS key

```python
kms_key = client.kms.create_key(
    name="my-key",
    project_id="<project-id>",
    encryption_algorithm=SymmetricEncryption.AES_GCM_256,
    description=None # Optional
)
```

**Parameters:**
- `name` (str): The name of the key (must be slug-friendly).
- `project_id` (str): The ID of your project.
- `encryption_algorithm` (SymmetricEncryption): The encryption algorithm this key should use.
- `description` (str, optional): A description of your key.

**Returns:**
- `KmsKey`: The newly created key.

#### Update KMS key

```python
updated_key = client.kms.update_key(
    key_id="<key-id>",
    name="my-updated-key", # Optional
    description="Updated description", # Optional
    is_disabled=True # Optional
)
```

**Parameters:**
- `key_id` (str): The ID of the key to be updated.
- `name` (str, optional): The updated name of the key (must be slug-friendly).
- `description` (str): The updated description of the key.
- `is_disabled` (str): The flag to disable operations with this key.

**Returns:**
- `KmsKey`: The updated key.

#### Delete KMS key

```python
deleted_key = client.kms.delete_key(
    key_id="<key-id>"
)
```

**Parameters:**
- `key_id` (str): The ID of the key to be deleted.

**Returns:**
- `KmsKey`: The deleted key.

#### Encrypt data with KMS key

```python
encrypted_data = client.kms.encrypt_data(
    key_id="<key-id>",
    base64EncodedPlaintext="TXkgc2VjcmV0IG1lc3NhZ2U=" # must be base64 encoded
)
```

**Parameters:**
- `key_id` (str): The ID of the key to encrypt the data with.
- `base64EncodedPlaintext` (str): The plaintext data to encrypt (must be base64 encoded).

**Returns:**
- `str`: The encrypted ciphertext.

#### Decrypt data with KMS key

```python
decrypted_data = client.kms.decrypt_data(
    key_id="<key-id>",
    ciphertext="Aq96Ry7sMH3k/ogaIB5MiSfH+LblQRBu69lcJe0GfIvI48ZvbWY+9JulyoQYdjAx"
)
```

**Parameters:**
- `key_id` (str): The ID of the key to decrypt the data with.
- `ciphertext` (str): The ciphertext returned from the encrypt operation.

**Returns:**
- `str`: The base64 encoded plaintext.

### `folders`

This sub-class handles operations related to [folders](/documentation/platform/folder):

<Note>
  `update_folder` and `delete_folder` require `infisicalsdk` version 1.0.17 or newer.
</Note>

#### List folders

```python
folders = client.folders.list_folders(
    project_id="<project-id>",
    environment_slug="dev",
    path="/",
    recursive=False, # Optional
    last_secret_modified=None # Optional
)
```

**Parameters:**
- `project_id` (str): The ID of your project.
- `environment_slug` (str): The environment in which to list folders.
- `path` (str): The path to list folders from.
- `recursive` (bool, optional): Whether to list folders recursively from the specified path and downwards. Defaults to `False`.
- `last_secret_modified` (datetime, optional): The timestamp used to filter folders with secrets modified after the specified date. Defaults to `None`.

**Returns:**
- `ListFoldersResponse`: The response containing the list of folders.

#### Create folder

```python
new_folder = client.folders.create_folder(
    name="my-folder",
    environment_slug="dev",
    project_id="<project-id>",
    path="/", # Optional
    description=None # Optional
)
```

**Parameters:**
- `name` (str): The name of the folder to create.
- `environment_slug` (str): The slug of the environment to create the folder in.
- `project_id` (str): The ID of your project to create the folder in.
- `path` (str, optional): The path to create the folder in. Defaults to `/`.
- `description` (str, optional): An optional description label for the folder. Defaults to `None`.

**Returns:**
- `CreateFolderResponseItem`: The response containing the created folder.

#### Get folder by ID

```python
folder = client.folders.get_folder_by_id(
    id="<folder-id>"
)
```

**Parameters:**
- `id` (str): The ID of the folder to retrieve.

**Returns:**
- `SingleFolderResponseItem`: The response containing the folder details.
#### Update folder

```python
updated_folder = client.folders.update_folder(
    folder_id="<folder-id>",
    name="backend-api",
    project_id="<project-id>",
    environment_slug="dev",
    path="/", # Optional
    description="Secrets for the backend service" # Optional
)
```

**Parameters:**
- `folder_id` (str): The ID of the folder to update. Folders can only be updated by ID, so use `list_folders` to look the ID up if you only know the name.
- `name` (str): The new name of the folder. This is required, so pass the folder's current name to leave it unchanged.
- `project_id` (str): The ID of your project.
- `environment_slug` (str): The slug of the environment the folder is in.
- `path` (str, optional): The parent path the folder is in. Defaults to `/`.
- `description` (str, optional): A new description for the folder. Omitting it leaves the existing description unchanged, so it can't be used to clear one.

**Returns:**
- `UpdateFolderResponseItem`: The response containing the updated folder.

#### Delete folder

```python
deleted_folder = client.folders.delete_folder(
    folder_id_or_name="backend",
    project_id="<project-id>",
    environment_slug="dev",
    path="/", # Optional
    force_delete=False # Optional
)
```

**Parameters:**
- `folder_id_or_name` (str): The ID or the name of the folder to delete.
- `project_id` (str): The ID of your project.
- `environment_slug` (str): The slug of the environment the folder is in.
- `path` (str, optional): The parent path the folder is in. Defaults to `/`.
- `force_delete` (bool, optional): Whether to delete the folder even when it still contains secrets or subfolders. Defaults to `False`.

<Warning>
  Setting `force_delete` to `True` removes every secret and subfolder inside the folder along with it.
</Warning>

**Returns:**
- `DeleteFolderResponseItem`: The response containing the deleted folder. Unlike the other folder responses, it doesn't include a `path` field.

### `agent_vault.sessions`

This sub-class manages [Agent Vault sessions](/documentation/platform/agent-vault/sessions). A session lets an AI agent use the [services](/documentation/platform/agent-vault/services) in one [access bundle](/documentation/platform/agent-vault/access-bundles) until the session expires or someone revokes it.

What the client can do with sessions depends on the [Agent Vault role](/documentation/platform/agent-vault/access-control#product-membership) of the user or machine identity that the client logs in as:

| Role | Can create sessions with | Can list, get, label, and revoke |
| --- | --- | --- |
| **Admin** | Any access bundle | Every session |
| **Member** | The access bundles [granted](/documentation/platform/agent-vault/access-bundles#grant-access) to the identity | The identity's own sessions |

<Note>
  `agent_vault` requires `infisicalsdk` version 1.0.19 or newer.
</Note>

#### List sessions

```python
from infisical_sdk import AgentVaultSessionScope, AgentVaultSessionStatus

sessions = client.agent_vault.sessions.list(
    scope=AgentVaultSessionScope.MINE, # Optional
    statuses=[AgentVaultSessionStatus.ACTIVE], # Optional
    search="nightly deploy", # Optional
    limit=20, # Optional
    offset=0 # Optional
)
```

**Parameters:**
- `scope` (Union[AgentVaultSessionScope, str], optional): whose sessions to list, either `AgentVaultSessionScope.MINE` (`"mine"`) for the identity's own sessions or `AgentVaultSessionScope.ALL` (`"all"`) for every session if the identity is an admin (defaults to `AgentVaultSessionScope.MINE`)
- `statuses` (List[Union[AgentVaultSessionStatus, str]], optional): the statuses to include, from `AgentVaultSessionStatus.ACTIVE` (`"active"`), `AgentVaultSessionStatus.REVOKED` (`"revoked"`), and `AgentVaultSessionStatus.EXPIRED` (`"expired"`) (defaults to all three)
- `search` (str, optional): text to find in each session's [label](/documentation/platform/agent-vault/sessions#label-a-session), owner name, owner email, or access bundle name
- `limit` (int, optional): the maximum number of sessions to return, from 1 to 100 (defaults to `20`)
- `offset` (int, optional): the number of sessions to skip (defaults to `0`)

**Returns:**
- `ListAgentVaultSessionsResponse`: the sessions in `sessions`, and the total number of matching sessions in `totalCount`

#### Get session

```python
session = client.agent_vault.sessions.get(
    session_id="<session-id>"
)
```

**Parameters:**
- `session_id` (str): the ID of the session

**Returns:**
- `AgentVaultSession`: the session

#### Create session

```python
session = client.agent_vault.sessions.create(
    access_bundle="<access-bundle-name>",
    ttl="1h", # Optional
    label="nightly deploy" # Optional
)
```

**Parameters:**
- `access_bundle` (str): the name of the access bundle that the agent can use during the session
- `ttl` (str, optional): how long the session lasts, as a duration of at least one minute such as `30m`, `8h`, or `7d`, or as `never` for a session that doesn't expire (defaults to `7d`)
- `label` (str, optional): a short description of what the session is for, such as `nightly deploy` (up to 128 characters, without line breaks, tabs, or invisible characters)

**Returns:**
- `CreatedAgentVaultSession`: the new session, with the session token in `token` (Infisical returns the token only once)

To pass `session.token` to the agent, follow the steps in [Start the agent with the session token](/documentation/platform/agent-vault/sessions-api#step-4-start-the-agent-with-the-session-token).

#### Update session label

Add, change, or remove a session's label, for example to record what the agent is working on. You can also change the label after the session expires or is revoked, unless the user or machine identity that owns the session was deleted.

```python
session = client.agent_vault.sessions.update(
    session_id="<session-id>",
    label="support ticket triage"
)
```

**Parameters:**
- `session_id` (str): the ID of the session
- `label` (Optional[str]): the new label, or `None` to remove the label (up to 128 characters, without line breaks, tabs, or invisible characters)

**Returns:**
- `AgentVaultSession`: the updated session

#### Revoke session

Revoke a session when its agent finishes, even if the agent fails. The proxy stops attaching credentials for the session within one [poll interval](/documentation/platform/agent-vault/proxies#poll-interval).

If the agent can run longer than the client's access token lasts, log in again before you revoke the session, because the SDK doesn't renew the access token. A `ttl` close to how long the agent runs limits how long the session stays active if the revoke fails.

```python
session = client.agent_vault.sessions.create(access_bundle="<access-bundle-name>", ttl="1h")
try:
    run_agent(session.token) # Your code that starts the agent with the session token
finally:
    client.agent_vault.sessions.revoke(session_id=session.id)
```

**Parameters:**
- `session_id` (str): the ID of the session

**Returns:**
- `AgentVaultSession`: the revoked session, with `accessBundles` set to `None` (call `get` for the access bundle)

### `agent_vault.proxies`

This sub-class manages [Agent Vault proxies](/documentation/platform/agent-vault/proxies). A proxy attaches API credentials to the requests that agents send through it.

To use any method in this section except `list`, the client must log in as a user or machine identity with the **Admin** role in [Agent Vault](/documentation/platform/agent-vault/access-control#product-membership).

<Note>
  `agent_vault` requires `infisicalsdk` version 1.0.19 or newer.
</Note>

#### List proxies

```python
proxies = client.agent_vault.proxies.list(
    search="edge", # Optional
    order_by="name", # Optional
    order_direction="asc", # Optional
    limit=20, # Optional
    offset=0 # Optional
)
```

**Parameters:**
- `search` (str, optional): text to find in proxy names
- `order_by` (str, optional): what to sort the proxies by, `name` or `createdAt` (defaults to `createdAt`)
- `order_direction` (str, optional): the direction to sort in, `asc` or `desc` (defaults to `desc`)
- `limit` (int, optional): the maximum number of proxies to return, from 1 to 100 (defaults to `20`)
- `offset` (int, optional): the number of proxies to skip (defaults to `0`)

**Returns:**
- `ListAgentVaultProxiesResponse`: the proxies in `proxies`, and the total number of matching proxies in `totalCount`

If the client logs in as a member, each proxy's `trafficPolicy`, `allowedHosts`, `pollInterval`, and `createdAt` fields are `None`.

#### Create proxy

```python
from infisical_sdk import AgentVaultTrafficPolicy

response = client.agent_vault.proxies.create(
    name="edge-proxy",
    traffic_policy=AgentVaultTrafficPolicy.BUNDLE_HOSTS, # Optional
    allowed_hosts=["registry.npmjs.org", "pypi.org"], # Optional
    poll_interval=60 # Optional
)
```

**Parameters:**
- `name` (str): the name of the proxy, in lowercase letters, numbers, and hyphens (up to 64 characters)
- `traffic_policy` (Union[AgentVaultTrafficPolicy, str], optional): the proxy's [traffic policy](/documentation/platform/agent-vault/proxies#traffic-policy), either `AgentVaultTrafficPolicy.ANY_HOST` (`"any-host"`) to forward requests to any host or `AgentVaultTrafficPolicy.BUNDLE_HOSTS` (`"bundle-hosts"`) to refuse requests to hosts that no service in the session's access bundle covers (defaults to `AgentVaultTrafficPolicy.ANY_HOST`)
- `allowed_hosts` (Union[List[str], str], optional): hosts that agents can reach under `AgentVaultTrafficPolicy.BUNDLE_HOSTS` even if no service covers them, as a list or a comma-separated string (see [Exceptions](/documentation/platform/agent-vault/proxies#exceptions))
- `poll_interval` (int, optional): how often, in seconds, the proxy checks its sessions and settings with Infisical, from 10 to 300 (defaults to `60`)

**Returns:**
- `AgentVaultProxyWithTokenResponse`: the proxy in `proxy`, and its proxy token in `proxyToken` (Infisical returns the token only once)

To start the proxy with the proxy token, run one of the commands in [Create a proxy and start it](/documentation/platform/agent-vault/proxies#create-a-proxy-and-start-it).

#### Update proxy

The proxy's name and settings that you don't pass stay as they are. If the proxy is running, it applies the changes within one poll interval.

```python
from infisical_sdk import AgentVaultTrafficPolicy

proxy = client.agent_vault.proxies.update(
    proxy_id="<proxy-id>",
    name="edge-proxy", # Optional
    traffic_policy=AgentVaultTrafficPolicy.BUNDLE_HOSTS, # Optional
    allowed_hosts=["pypi.org"], # Optional
    poll_interval=30 # Optional
)
```

**Parameters:**
- `proxy_id` (str): the ID of the proxy
- `name` (str, optional): the new name of the proxy
- `traffic_policy` (Union[AgentVaultTrafficPolicy, str], optional): the new traffic policy
- `allowed_hosts` (Union[List[str], str], optional): the new exceptions, which replace the current ones
- `poll_interval` (int, optional): the new poll interval in seconds, from 10 to 300
- `clear_allowed_hosts` (bool, optional): set to `True` to remove every exception (raises a `ValueError` if you also pass `allowed_hosts`)

**Returns:**
- `AgentVaultProxy`: the updated proxy

#### Delete proxy

```python
proxy = client.agent_vault.proxies.delete(
    proxy_id="<proxy-id>"
)
```

**Parameters:**
- `proxy_id` (str): the ID of the proxy

<Warning>
  You can't undo deleting a proxy. To stop a proxy temporarily, [revoke its access](#revoke-proxy) instead.
</Warning>

**Returns:**
- `AgentVaultProxy`: the deleted proxy, with values only in `id` and `name`

#### Rotate proxy token

Issue a new proxy token if the current one leaked, or to restore a proxy whose access you revoked. The old token stops working right away. To restart the proxy and its agents, follow the steps in [Rotate a proxy's token](/documentation/platform/agent-vault/proxies#rotate-a-proxy’s-token).

```python
response = client.agent_vault.proxies.rotate_token(
    proxy_id="<proxy-id>"
)
```

**Parameters:**
- `proxy_id` (str): the ID of the proxy

**Returns:**
- `AgentVaultProxyWithTokenResponse`: the proxy in `proxy`, and the new proxy token in `proxyToken` (Infisical returns the token only once)

#### Revoke proxy

Revoke a proxy's access if you think a machine that runs the proxy is compromised. The proxy stops attaching credentials to requests until you [rotate its token](#rotate-proxy-token).

```python
proxy = client.agent_vault.proxies.revoke(
    proxy_id="<proxy-id>"
)
```

**Parameters:**
- `proxy_id` (str): the ID of the proxy

**Returns:**
- `AgentVaultProxy`: the revoked proxy