Skip to main content

Python SDK Guide (aptia-one-sdk)

The Python SDK provides strongly-typed Pydantic v2 models and typed API clients for Python 3.10 and newer.

Installation​

Via Pip​

pip install aptia-one-sdk requests

From Downloaded Bundle​

Download the zip archive from the Download Center, extract it, and install:

pip install ./path-to/python-sdk

Architecture Note: Token Exchange​

No Built-In OAuth Token Exchange

The aptia-one-sdk package is a typed REST client. It does not exchange credentials with AWS Cognito or handle token lifecycle automatically. Applications must perform the client credentials exchange and provide the token to Configuration as demonstrated below.

Complete Executable Example​

import os
import uuid
import requests
import aptia_one_sdk
from aptia_one_sdk.rest import ApiException

def get_cognito_access_token(auth_url: str, client_id: str, client_secret: str) -> str:
    """Acquires OAuth 2.0 access token via client credentials grant."""
    response = requests.post(
        f"{auth_url}/oauth2/token",
        data={
            "grant_type": "client_credentials",
            "client_id": client_id,
            "client_secret": client_secret,
            "scope": "aptia/participants.read aptia/enrollments.read",
        },
        headers={"Content-Type": "application/x-www-form-urlencoded"},
        timeout=15,
    )
    response.raise_for_status()
    return response.json()["access_token"]

def main():
    is_sandbox = True
    base_url = "https://api.development.aptiaone.com" if is_sandbox else "https://api.development.aptiaone.com"
    auth_url = (
        "https://auth-api-development-us-east-1.auth.us-east-1.amazoncognito.com"
        if is_sandbox
        else "https://auth-api-development-us-east-1.auth.us-east-1.amazoncognito.com"
    )

    client_id = os.environ.get("APTIA_CLIENT_ID", "your-client-id")
    client_secret = os.environ.get("APTIA_CLIENT_SECRET", "your-client-secret")
    tenant_id = "tenant-001"

    # Step 1: Obtain OAuth 2.0 Token
    access_token = get_cognito_access_token(auth_url, client_id, client_secret)

    # Step 2: Configure SDK
    configuration = aptia_one_sdk.Configuration(
        host=base_url,
        access_token=access_token,
    )

    # Step 3: Initialize ApiClient and set tenant / correlation headers
    with aptia_one_sdk.ApiClient(configuration) as api_client:
        api_client.set_default_header("X-Aptia-Tenant-Id", tenant_id)
        api_client.set_default_header("X-Correlation-Id", str(uuid.uuid4()))

        participants_api = aptia_one_sdk.ParticipantsApi(api_client)

        try:
            # Step 4: Execute typed request
            api_response = participants_api.list_participants(
                page_number=1,
                page_size=10,
                search="Doe"
            )
            print(f"Total participants found: {api_response.total_count}")
            for participant in (api_response.items or []):
                print(f"- {participant.first_name} {participant.last_name} ({participant.id})")

        except ApiException as e:
            print(f"Aptia API Error ({e.status}): {e.body}")

if __name__ == "__main__":
    main()