Getting Started

Installation

pip install keystoneos

View on PyPI | Source on GitHub

Requires Python 3.10+. Dependencies: httpx (HTTP client) and pydantic (type validation).

Initialize

from keystoneos import KeystoneClient

client = KeystoneClient(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET",
    environment="production",
)

# Use as async context manager for clean connection handling
async with client:
    settlements = await client.settlements.list()

from keystoneos import KeystoneSyncClient

client = KeystoneSyncClient(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET",
)

with client:
    settlements = client.settlements.list()

The async client is recommended for production. The sync client wraps the async client for scripts, notebooks, and frameworks without native async support.

Configuration

Option	Type	Default	Description
`client_id`	`str`	required	Auth0 M2M client ID
`client_secret`	`str`	required	Auth0 M2M client secret
`environment`	`str`	`"production"`	`"development"`, `"staging"`, or `"production"`
`base_url`	`str`	per environment	Override API base URL
`auth_domain`	`str`	per environment	Override Auth0 domain
`audience`	`str`	per environment	Override Auth0 audience
`timeout`	`float`	`30.0`	Request timeout in seconds
`retry`	`RetryConfig`	3 retries, 0.5s base	Retry configuration

RetryConfig

Override retry behavior:

from keystoneos import RetryConfig

client = KeystoneClient(
    client_id="...",
    client_secret="...",
    retry=RetryConfig(
        max_retries=5,
        base_delay=1.0,
        max_delay=60.0,
        retryable_status_codes={429, 500, 502, 503, 504},
    ),
)

Resources

client.instructions   # Submit, get, list, cancel paired instructions
client.settlements    # Create, get, list, events, compliance decisions
client.templates      # List and get settlement templates (read-only)
client.webhooks       # CRUD + test, rotate secret, delivery logs, signature verification
client.environments   # CRUD + deactivate platform environments
client.compliance     # approve() and reject() convenience methods

Idempotency Keys

Keys starting with match- are reserved for keys KeyStone derives and are refused with 422. The default generator produces ks-{uuid4}, which is outside that prefix. A prefix you pass becomes the start of the key ({prefix}-{uuid4}), and any key starting with match- is refused: a prefix of match yields match-{uuid4} and is refused, while matcher yields matcher-{uuid4} and is not.

key = client.generate_idempotency_key()            # "ks-{uuid4}"
key = client.generate_idempotency_key("my-prefix")  # "my-prefix-{uuid4}"

# Safe to retry - same key returns existing resource
settlement = await client.settlements.create({
    "idempotency_key": key,
    # ...
})

Pagination

All list methods return PaginatedResponse[T] with convenience properties:

result = await client.settlements.list(limit=20)

print(result.items)       # list[Settlement]
print(result.total)       # Total count
print(result.has_more)    # True if more pages exist
print(result.next_offset) # Offset for next page

# Iterate through all pages
offset = 0
while True:
    page = await client.settlements.list(limit=50, offset=offset)
    for settlement in page.items:
        process(settlement)
    if not page.has_more:
        break
    offset = page.next_offset

Overview

Backend SDKs

Frontend Library

Tools

Installation

Initialize

Configuration

RetryConfig

Resources

Idempotency Keys

​Installation

​Initialize

​Configuration

​RetryConfig

​Resources

​Idempotency Keys

​Pagination

Installation

Initialize

Configuration

RetryConfig

Resources

Idempotency Keys

Pagination