Version: Axidian Privilege 3.4

Python SDK

Python SDK provides an API for retrieving passwords and SSH keys of Axidian Privilege accounts. The solution is suitable for integrating PAM into CI/CD automations, Python scripts, orchestration systems, and other processes that require secure credential management.

All requests to retrieve and view credentials are logged in the Events section.

Requirements

Python 3.9 or higher is required to work with Python SDK.

Prerequisites

To set up Python SDK, perform the following steps:

Go to the AAPM Python SDK package folder and execute the command:
```
pip install pam_aapm-3.4.0-py3-none-any.whl
```
Go to the Axidian Privilege administrator console and add an application.
For the application, add a permission with the Allow view account credentials option enabled.
The permission will allow the application to use passwords and SSH keys of PAM accounts.
Assign application administrators who can view its password.
Open the Axidian Privilege user console and go to the Applications tab.
View the application password and save it.

Next, open any Python development environment and configure access to the Axidian Privilege server.

Quick start

from pam_aapm import PamClient

# Using a context manager (recommended)
with PamClient(
    idp_url="https://pam.company.com/idp",
    core_url="https://pam.company.com/core",
    username="my-app",
    password="app-password",
) as client:
    # Retrieving a password
    db_password = client.get_password("DB-SERVER/admin")

    # Retrieving an SSH key
    ssh_key = client.get_ssh_key("LINUX-SERVER/deploy")

    # Retrieving a list of available accounts
    accounts = client.get_accounts()
    for account in accounts:
        print(f"{account.display_name}: password={account.has_password}, key={account.has_key}")

Authentication

PamClient is the main Python SDK class for interacting with Axidian Privilege. It provides an API for authentication and credential retrieval. To establish a connection to the PAM server and obtain access tokens, specify the parameters from the table for the PamClient class.

PamClient parameters

Parameter	Environment variable	Required	Description
`idp_url`	`PAM_IDP_SERVER`	Required	URL of the Axidian Privilege IdP component
`core_url`	`PAM_CORE_SERVER`	Required	URL of the Axidian Privilege Core component
`username`	`PAM_USERNAME`	Required	Application name
`password`	`PAM_PASSWORD`	Required	Password of the specified application. The application administrator can view the password in the user console.
`client_id`	—	Optional	Identifier of the client application requesting the token. Default: `"aapm-tool"`.
`scope`	—	Optional	API access request via the OAuth2 protocol. Default: `"pam-api"`.
`verify_ssl`	`PAM_VERIFY_SSL`	Optional	Server SSL certificate verification: `True` — required `False` — not required Default: `True`. Note: Enabled verification reduces the risk of data interception. If you have disabled verification, it is recommended to highlight this in the script and leave a comment.
`ca_cert`	`PAM_CA_CERT`	Optional	Path to the certificate for SSL connection verification. Specify if the PAM server uses a certificate signed by an internal CA. The certificate must be in PEM format. Example: `ca_cert="/path/to/ca.crt"`. Default: `None`.
`timeout`	—	Optional	Response timeout for a request, in seconds. Default: `30.0`.
`accounts_cache_ttl`	—	Optional	Time-to-live (TTL) for the accounts cache, in seconds. Default: `300`.

After configuring access, call one of the methods to retrieve credentials.

Note

It is recommended to use the with context manager.
In this case, the connection to PAM is closed automatically and access tokens are deleted.

Example with authentication parameters
from pam_aapm import PamClient

with PamClient(
    idp_url="https://pam.company.com/idp",
    core_url="https://pam.company.com/core",
    username="my-app",
    password="app-password",
) as client:
    password = client.get_password("SERVER/account")

Example with environment variables (recommended for CI/CD automations)
import os
from pam_aapm import PamClient

with PamClient(
    idp_url=os.environ["PAM_IDP_SERVER"],
    core_url=os.environ["PAM_CORE_SERVER"],
    username=os.environ["PAM_USERNAME"],
    password=os.environ["PAM_PASSWORD"],
    verify_ssl=os.environ.get("PAM_VERIFY_SSL", "true").lower() == "true",
    ca_cert=os.environ.get("PAM_CA_CERT"),
) as client:
    password = client.get_password("SERVER/account")

Methods

Python SDK methods allow you to retrieve the following from Axidian Privilege:

account password
account SSH key
list of available accounts

`get_password()`

The method is used to retrieve a PAM account password.

get_password(account_name, reason=None)

get_password() parameters

Parameter	Required	Description
`account_name`	Required	Account name in the following format: `LOCATION/username` — recommended format `LOCATION\username` — requires escaping in Python scripts, for example `"DB-SERVER\\admin"`
`reason`	Optional	Reason for retrieving credentials. Whether a reason is required is determined by the policy applied to the account. Default: `None`.

from pam_aapm import PamClient

with PamClient(
    idp_url="https://pam.company.com/idp",
    core_url="https://pam.company.com/core",
    username="my-app",
    password="app-password",
) as client:
    # Retrieving a password
    password = client.get_password("DB-SERVER/db_admin")

    # Retrieving a password when a reason is required
    password = client.get_password(
        "PROD-SERVER/admin",
        reason="Scheduled maintenance"
    )

`get_ssh_key()`

The method is used to retrieve a PAM account SSH key.

get_ssh_key(account_name, decrypt=True, reason=None)

get_ssh_key() parameters

Parameter	Required	Description
`account_name`	Required	Account name in the following format: `LOCATION/username` — recommended format `LOCATION\username` — requires escaping in Python scripts, for example `"DB-SERVER\\admin"`
`decrypt`	Optional	Return the decrypted SSH key: `True` — return `False` — do not return Default: `True`.
`reason`	Optional	Reason for retrieving credentials. Whether a reason is required is determined by the policy applied to the account. Default: `None`.

Response parameters

Parameter	Description
If `decrypt=True` in the request
`key`	Account SSH key in PEM format
If `decrypt=False` in the request
`key`	Encrypted SSH key
`passphrase`	Passphrase of the encrypted key
`file_name`	Key file name

from pam_aapm import PamClient

with PamClient(
   idp_url="https://pam.company.com/idp",
   core_url="https://pam.company.com/core",
   username="my-app",
   password="app-password",
) as client:
   # Decrypted key
   key = client.get_ssh_key("LINUX-SERVER/automation")

   # Encrypted key with passphrase
   key_data = client.get_ssh_key("LINUX-SERVER/automation", decrypt=False)
   print(f"Key: {key_data.key}")
   print(f"Passphrase: {key_data.passphrase}")

`get_accounts()`

The method is used to retrieve a list of available PAM accounts.

get_accounts(force_refresh=False)

get_accounts() parameters

Parameter	Required	Description
`force_refresh`	Optional	Force cache refresh: `True` — reset cache `False` — do not reset Default: `False`.

Response parameters

Parameter	Description
`id`	Account identifier
`display_name`	Account name
`requires_reason`	A reason for viewing credentials is required: `true` — required `false` — not required Whether a reason is required is determined by the policy applied to the account.
`has_password`	Account password: `true` — set `false` — not set
`has_key`	Account SSH key: `true` — set `false` — not set
`is_key_supported`	Adding an SSH key is available for the account: `true` — available `false` — not available

from pam_aapm import PamClient
with PamClient(
    idp_url="https://pam.company.com/idp",
    core_url="https://pam.company.com/core",
    username="my-app",
    password="app-password",
) as client:
    accounts = client.get_accounts(force_refresh=False)

    for account in accounts:
        print(f"Account: {account.display_name}")
        print(f"  - Has password: {account.has_password}")
        print(f"  - Has SSH key: {account.has_key}")
        print(f"  - Requires reason: {account.requires_reason}")

`close()`

The method releases system resources and is called automatically when the with context manager is used.

If the context manager is not used, call close() when the connection to PAM is no longer needed.

close()

Example without using a context manager
from pam_aapm import PamClient

# Creating a client instance
client = PamClient(
    idp_url="https://pam.company.com/idp",
    core_url="https://pam.company.com/core",
    username="my-app",
    password="app-password",
)

password = client.get_password("DB-SERVER/db_admin")

client.close()

Exceptions and error handling

Exceptions are events that report errors during script execution. Exception handling allows you to intercept an error without forcefully terminating the program.

Exception list

Exception	Description
`AuthenticationError`	Authentication error in Axidian Privilege. Change the credentials or refresh the access token.
`AccountNotFoundError`	The account was not found or is unavailable. Make sure the account has not been deleted in Axidian Privilege or that the account name in the request is correct.
`PasswordNotSetError`	The password for the account is not set. Occurs when calling the `get_password()` method if the account does not have a password configured.
`SshKeyNotSetError`	The SSH key for the account is not set. Occurs when calling the `get_ssh_key()` method if the account does not have an SSH key configured.
`ReasonRequiredError`	A request reason is required according to the policy. Fill in the `reason` parameter in the request.
`ConfigurationError`	Configuration error. Make sure the URLs for IdP and Core are specified correctly, or add the missing parameters to the request.
`ApiError`	API server error. Review the HTTP response code.
`PamConnectionError`	Server connection error. Check the availability of the IdP and Core components.
`ValidationError`	Input data processing error. Make sure the IdP and Core components are accessible and the request parameters are specified correctly.

Exception handling example

from pam_aapm import (
    PamClient,
    AuthenticationError,
    AccountNotFoundError,
    PasswordNotSetError,
    ReasonRequiredError,
    SshKeyNotSetError,
    PamConnectionError,
    PamError,
)

try:
    with PamClient(
        idp_url="https://pam.company.com/idp",
        core_url="https://pam.company.com/core",
        username="my-app",
        password="app-password",
    ) as client:
        password = client.get_password("SERVER/account")

except AuthenticationError as e:
    print(f"Authentication error: {e}")
except AccountNotFoundError as e:
    print(f"Account not found: {e.account_name}")
except PasswordNotSetError as e:
    print(f"Password not set: {e.account_name}")
except ReasonRequiredError as e:
    print(f"Reason required: {e.account_name}")
except SshKeyNotSetError as e:
    print(f"SSH key not set: {e.account_name}")
except PamConnectionError as e:
    print(f"Connection error: {e}")
except PamError as e:
    print(f"PAM error: {e}")

Security recommendations

Do not store credentials in scripts. For improved security, use environment variables or secret vaults.
Use the with context manager. In this case, the connection to Axidian Privilege is closed automatically and access tokens are deleted after the request is processed.
SSL connection verification is enabled by default. Disable verification only for testing in isolated environments.
When logging exceptions, avoid recording account names so that they are not persisted in the logs.

Prerequisites​

Quick start​

Authentication​

Methods​

get_password()​

get_ssh_key()​

get_accounts()​

close()​

Exceptions and error handling​

Security recommendations​