Akeyless

Backend for managing secrets using the Akeyless Vault.

1. Overview
2. access_id
3. access_type
4. jwt_env_key
5. api_host
6. profile
7. auto_guess_type
8. auth_token_ttl
9. token_refresh_buffer
10. cache_storage

Overview

This class provides integration with Akeyless vault services, allowing you to store, retrieve, and manage secrets. It supports different types of secrets (static, dynamic, rotated) and includes authentication mechanisms for AWS IAM, SAML, and JWT.

Token Validation and Caching

Authentication tokens are automatically cached and validated to minimize API calls:

• All auth methods (AWS IAM, JWT, SAML) return a (token, expiry) tuple
• JWT/AWS IAM: Token expiry is extracted from the nested creds.expiry field in the auth response, with a fallback to auth_token_ttl when creds is not populated
• SAML: Reads credentials file first; only forces re-authentication (via list-items) when token is expired
• Tokens are automatically refreshed when expired or within the configured token_refresh_buffer (default: 5 minutes)

Cache Storage

The cache_storage parameter (inherited from Secrets) accepts an instance of a subclass of SecretCache. This enables caching secrets in external stores like AWS Parameter Store, AWS Secrets Manager, Redis, etc.

Example: Using Cache Storage

from clearskies.secrets.cache_storage import SecretCache
import clearskies


class MyCache(SecretCache):
    def get(self, path: str) -> str | None:
        # Retrieve from your cache
        return None

    def set(self, path: str, value: str, ttl: int | None = None) -> None:
        # Store in your cache
        pass

    def delete(self, path: str) -> None:
        # Remove from your cache
        pass

    def clear(self) -> None:
        # Clear all cached secrets
        pass


secrets = clearskies.secrets.Akeyless(
    access_id="p-abc123",
    access_type="aws_iam",
    cache_storage=MyCache(),
)
# First call fetches from Akeyless and caches
secret_value = secrets.get("/path/to/secret")
# Subsequent calls return from cache
secret_value = secrets.get("/path/to/secret")
# Force refresh from Akeyless
secret_value = secrets.get("/path/to/secret", refresh=True)

access_id

Required

The access ID for the Akeyless service

This must match the pattern p-[0-9a-zA-Z]+ (e.g., “p-abc123”)

access_type

Required

The authentication method to use

Must be one of “aws_iam”, “saml”, or “jwt”

jwt_env_key

Optional

The environment variable key that contains the JWT when using JWT authentication

This is required when access_type is “jwt”

api_host

Optional

The Akeyless API host to connect to

Defaults to “https://api.akeyless.io”

profile

Optional

The SAML profile name when using SAML authentication

Must match the pattern [0-9a-zA-Z-]+ if provided

auto_guess_type

Optional

Whether to automatically guess the secret type

When enabled, the system will check the secret type (static, dynamic, rotated) and call the appropriate method to retrieve it.

auth_token_ttl

Optional

Default TTL (in seconds) for auth tokens when expiry is not provided by the auth response

Defaults to 60 minutes (3600 seconds) to match Akeyless’s 1-hour token lifetime

token_refresh_buffer

Optional

Time buffer (in seconds) before token expiry to trigger re-authentication

When a token will expire within this time window, it will be considered expired and re-authentication will be triggered. Defaults to 5 minutes (300 seconds).

cache_storage

Optional

Optional cache storage configuration (can be a SecretCache instance).