Quickstart

This guide covers getting started with the Amorphic SDK using the enhanced wrapper classes.

Installation

Install the Amorphic SDK using pip:

pip install amorphic-sdk wheel file

Basic Usage

The Amorphic SDK provides wrapper classes that simplify authentication and provide enhanced functionality. The recommended approach fetches all configuration from AWS SSM Parameter Store, keeping credentials out of source code entirely.

import certifi
import boto3
from openapi_client.amorphic_api_client import AmorphicApiClient
from openapi_client.api.datasets_api import DatasetsApi

# Fetch configuration from SSM Parameter Store
ssm = boto3.client('ssm')
api_gw_url = ssm.get_parameter(Name='adp/amorphic/config/apigwurl', WithDecryption=False)['Parameter']['Value']  # String type; use WithDecryption=True for SecureString
role_id    = ssm.get_parameter(Name='adp/amorphic/config/roleid',   WithDecryption=False)['Parameter']['Value']  # String type; use WithDecryption=True for SecureString

# PAT token is fetched from SSM directly by the SDK
client = AmorphicApiClient.create_with_auth(
    host=api_gw_url,
    role_id=role_id,
    ssl_ca_cert=certifi.where(),
    ssm_parameter='adp/amorphic/config/pattoken'
)

# Create the datasets API instance
datasets_api = DatasetsApi(client)

try:
    datasets = datasets_api.list_datasets(role_id=role_id)
    print(f"Found {len(datasets.datasets)} datasets")
except Exception as e:
    print(f"Failed to list datasets: {e}")
    raise

Authentication Options

The wrapper class supports the following authentication methods.

AWS SSM Parameter Store (Recommended):

Suitable for all operational and automated workflows. The PAT token is stored as a SecureString parameter and retrieved at runtime.

client = AmorphicApiClient.create_with_auth(
    host=api_gw_url,
    role_id=role_id,
    ssl_ca_cert=certifi.where(),
    ssm_parameter='adp/amorphic/config/pattoken'
)

AWS Secrets Manager:

Use when the security policy requires secrets to be stored in Secrets Manager or when rotation support is needed. The secret value must be stored in plain text format.

client = AmorphicApiClient.create_with_auth(
    host=api_gw_url,
    role_id=role_id,
    ssl_ca_cert=certifi.where(),
    secret_arn='arn:aws:secretsmanager:<region>:<account>:secret:<secret-name>'
)

Environment Variable (Local development only):

Variables must be set at the OS level before running the script—do not assign them inside application code, as that defeats the purpose of environment-based isolation. This method is intended only for local testing, not for production or shared environments.

# Set in the shell before running the script
export PAT_TOKEN="<personal-access-token>"
export API_GW_URL="<api-gateway-url>"
export ROLE_ID="<role-id>"

import os
import certifi
from openapi_client.amorphic_api_client import AmorphicApiClient

client = AmorphicApiClient.create_with_auth(
    host=os.environ['API_GW_URL'],
    role_id=os.environ['ROLE_ID'],
    ssl_ca_cert=certifi.where(),
    env_var='PAT_TOKEN'    # reads from OS environment; not set in code
)

Direct Token (Quick testing only):

Passing the token directly is discouraged for any persistent use because it encourages embedding tokens in source files. Reserve this for one-off debugging sessions.

client = AmorphicApiClient.create_with_auth(
    host=api_gw_url,
    role_id=role_id,
    ssl_ca_cert=certifi.where(),
    token='<personal-access-token>'
)

For the full parameter reference, refer to the AmorphicApiClient documentation.

Discovery and Help

Use the built-in help system to explore available APIs:

from openapi_client.help import HelpCommand

# Create help instance
help_cmd = HelpCommand()

# List all available APIs
help_cmd.list_apis()

# Get details about a specific API
help_cmd.show_api_details('DatasetsApi')

# Describe a specific method
help_cmd.describe_api_method('DatasetsApi', 'create_dataset')

For detailed information about the help system and its capabilities, refer to the HelpCommand documentation.

Benefits of Using Wrapper Classes

  • Simplified Authentication: Automatic token management from multiple sources

  • Discovery Tools: Built-in help system to explore APIs and methods

Next Steps