Akeyless Python SDK

5.0.23 · active · verified Wed Apr 15

The Akeyless Python SDK facilitates integration of Python applications, libraries, or scripts with the Akeyless Vaultless Platform for secrets management, encryption, and access control. It allows secure interaction with Akeyless services to retrieve and manage various types of secrets. The current version is 5.0.23, and the library is actively maintained with frequent updates.

Common errors

```
ModuleNotFoundError: No module named 'akeyless'
```
cause The 'akeyless' package is not installed in the Python environment.

fix Install the package using pip: 'pip install akeyless'.
```
AttributeError: module 'akeyless' has no attribute 'V2Api'
```
cause The 'V2Api' class is not directly accessible from the 'akeyless' module.

fix Import the class correctly: 'from akeyless.api import V2Api'.
```
TypeError: 'NoneType' object is not callable
```
cause Attempting to call a method on an uninitialized or improperly configured 'akeyless' client instance.

fix Ensure the client is properly initialized: 'api_client = akeyless.ApiClient(configuration); api = akeyless.V2Api(api_client)'.
```
AttributeError: 'HTTPResponse' object has no attribute 'getheader'
```
cause This error occurs due to an incompatibility between certain older versions of the `akeyless` Python SDK (e.g., around v4.2.0) and newer versions of the `urllib3` library, where the `getheader` method was removed or changed on the `HTTPResponse` object.

fix Upgrade the `akeyless` SDK to its latest version (e.g., `pip install --upgrade akeyless`) to ensure compatibility with recent `urllib3` versions. As a temporary workaround for very specific older SDK versions, one might consider downgrading `urllib3` (e.g., `pip install 'urllib3<2'`).
```
Failed to authenticate token based access. Status 401 Unauthorized.
```
cause This error indicates that the Akeyless credentials provided (e.g., `access_id`, `access_key`, or the authentication token) are incorrect, expired, or the authentication method used does not have the necessary permissions within the Akeyless platform.

fix Verify that your `access_id` and `access_key` (or other authentication parameters like `uid_token` for Universal Identity) are correct and active in your Akeyless account. Ensure the associated authentication method has the required permissions and that the token is valid and not expired.

Warnings

gotcha Direct use of long-lived API keys (Access ID/Access Key) in code is a security anti-pattern. Akeyless recommends using short-lived tokens generated via Universal Identity or cloud-native identity providers (e.g., AWS IAM, GitHub OIDC) for authentication in production environments to minimize credential exposure.
Fix: Implement authentication using Akeyless Universal Identity (UID) or leverage cloud-native authentication methods like AWS IAM, Azure AD, or GitHub OIDC. Ensure tokens are rotated frequently and have the least necessary privileges.
gotcha The default Akeyless API host is `https://api.akeyless.io`. For on-premise Akeyless Gateways or specific Akeyless environments (e.g., US, EU regions), the `configuration.host` parameter must be explicitly set to the correct gateway URL or regional endpoint.
Fix: Set `configuration.host = "YOUR_AKEYLESS_GATEWAY_URL"` or the appropriate regional API endpoint during client configuration.
gotcha When updating a static secret, the `akeyless.update_secret_val` method (or equivalent API call) by default overwrites the latest version. To retain previous versions of the secret, the `keep_prev_version=true` option must be explicitly set. Failing to do so will result in the loss of previous secret values.
Fix: Always use the `keep_prev_version=true` parameter when you intend to preserve historical versions of a static secret during an update operation.
breaking There is an older, deprecated package `akeyless-api-gateway` (last updated in 2020, version 0.1.2) which is distinct from the current `akeyless` SDK. Installing or attempting to use `akeyless-api-gateway` instead of `akeyless` will lead to outdated APIs, incorrect import paths, and potentially missing functionality.
Fix: Ensure you are installing and importing the correct package: `pip install akeyless` and `import akeyless`.
gotcha After authenticating with Akeyless and obtaining a session token, this token must be explicitly passed with every subsequent API request that requires authentication. The SDK does not automatically persist or re-use the token across separate API calls without it being provided.
Fix: Store the `token` returned from the authentication response and include it as a parameter (e.g., `token=token`) in all subsequent authenticated API method calls.

Install

pip install akeyless Install Akeyless Python SDK

Imports

akeyless
```
import akeyless
```
ApiException
```
from akeyless.rest import ApiException
```

Quickstart

This quickstart demonstrates how to authenticate with Akeyless using an API Key and retrieve a static secret. It's crucial to manage your Access ID and Access Key securely, preferably via environment variables, and avoid hardcoding them. The `AKEYLESS_API_HOST` environment variable can be used to specify a different Akeyless Gateway endpoint if needed. After authentication, the obtained token must be included in subsequent API calls.

import akeyless
import os

# Configure API key authentication
# It's recommended to use environment variables or a secure configuration management system
access_id = os.environ.get('AKEYLESS_ACCESS_ID', 'your_access_id')
access_key = os.environ.get('AKEYLESS_ACCESS_KEY', 'your_access_key')

# Optional: Configure the Akeyless host (defaults to https://api.akeyless.io)
configuration = akeyless.Configuration(
    host=os.environ.get('AKEYLESS_API_HOST', 'https://api.akeyless.io')
)

with akeyless.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = akeyless.V2Api(api_client)

    try:
        # Authenticate to get a session token
        auth_body = akeyless.Auth(
            access_id=access_id,
            access_key=access_key
        )
        auth_response = api_instance.auth(auth_body)
        token = auth_response.token
        print(f"Authentication successful. Token obtained.")

        # Retrieve a static secret value
        secret_name = "/my-app/database-password"
        get_secret_body = akeyless.GetSecretValue(
            names=[secret_name],
            token=token
        )
        secret_response = api_instance.get_secret_value(get_secret_body)
        secret_value = secret_response.get(secret_name, "Secret not found")
        print(f"Retrieved secret '{secret_name}': {secret_value}")

    except ApiException as e:
        print(f"Exception when calling Akeyless API: {e}")
    except Exception as e:
        print(f"An unexpected error occurred: {e}")

view raw JSON →