{"id":6509,"library":"akeyless","title":"Akeyless Python SDK","description":"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.","status":"active","version":"5.0.23","language":"en","source_language":"en","source_url":"https://github.com/akeylesslabs/akeyless-python","tags":["secrets management","security","vault","API client","key management"],"install":[{"cmd":"pip install akeyless","lang":"bash","label":"Install Akeyless Python SDK"}],"dependencies":[],"imports":[{"symbol":"akeyless","correct":"import akeyless"},{"symbol":"ApiException","correct":"from akeyless.rest import ApiException"}],"quickstart":{"code":"import akeyless\nimport os\n\n# Configure API key authentication\n# It's recommended to use environment variables or a secure configuration management system\naccess_id = os.environ.get('AKEYLESS_ACCESS_ID', 'your_access_id')\naccess_key = os.environ.get('AKEYLESS_ACCESS_KEY', 'your_access_key')\n\n# Optional: Configure the Akeyless host (defaults to https://api.akeyless.io)\nconfiguration = akeyless.Configuration(\n    host=os.environ.get('AKEYLESS_API_HOST', 'https://api.akeyless.io')\n)\n\nwith akeyless.ApiClient(configuration) as api_client:\n    # Create an instance of the API class\n    api_instance = akeyless.V2Api(api_client)\n\n    try:\n        # Authenticate to get a session token\n        auth_body = akeyless.Auth(\n            access_id=access_id,\n            access_key=access_key\n        )\n        auth_response = api_instance.auth(auth_body)\n        token = auth_response.token\n        print(f\"Authentication successful. Token obtained.\")\n\n        # Retrieve a static secret value\n        secret_name = \"/my-app/database-password\"\n        get_secret_body = akeyless.GetSecretValue(\n            names=[secret_name],\n            token=token\n        )\n        secret_response = api_instance.get_secret_value(get_secret_body)\n        secret_value = secret_response.get(secret_name, \"Secret not found\")\n        print(f\"Retrieved secret '{secret_name}': {secret_value}\")\n\n    except ApiException as e:\n        print(f\"Exception when calling Akeyless API: {e}\")\n    except Exception as e:\n        print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Set `configuration.host = \"YOUR_AKEYLESS_GATEWAY_URL\"` or the appropriate regional API endpoint during client configuration.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always use the `keep_prev_version=true` parameter when you intend to preserve historical versions of a static secret during an update operation.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure you are installing and importing the correct package: `pip install akeyless` and `import akeyless`.","message":"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.","severity":"breaking","affected_versions":"< 1.0.0 (for `akeyless-api-gateway` package)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[{"fix":"Install the package using pip: 'pip install akeyless'.","cause":"The 'akeyless' package is not installed in the Python environment.","error":"ModuleNotFoundError: No module named 'akeyless'"},{"fix":"Import the class correctly: 'from akeyless.api import V2Api'.","cause":"The 'V2Api' class is not directly accessible from the 'akeyless' module.","error":"AttributeError: module 'akeyless' has no attribute 'V2Api'"},{"fix":"Ensure the client is properly initialized: 'api_client = akeyless.ApiClient(configuration); api = akeyless.V2Api(api_client)'.","cause":"Attempting to call a method on an uninitialized or improperly configured 'akeyless' client instance.","error":"TypeError: 'NoneType' object is not callable"},{"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'`).","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.","error":"AttributeError: 'HTTPResponse' object has no attribute 'getheader'"},{"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.","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.","error":"Failed to authenticate token based access. Status 401 Unauthorized."}]}