Tollara Service SDK (Python)
Package: tollara-service-sdk (PyPI). Import: import tollara_service_sdk.
Verify HMAC on incoming gateway requests, validate service keys, run usage pre-flight (service-key and JWT paths), gateway invoke, report usage, progress/completion, and poll async job status on the gateway.
This README covers the public SDK contract and usage examples.
Configuration
Recommended: TollaraClient
Use TollaraClient with one API origin (scheme + host, optional port).
| Setting | Default | Notes |
|---|---|---|
| API origin | https://api.tollara.ai (TollaraClient.DEFAULT_API_URL) |
Override with api_url=..., or env TOLLARA_API_URL for staging/tests — no trailing slash required |
| Service identity | From env TOLLARA_SERVICE_ID, or service_id=... |
Optional if Core can infer the service from the key |
| Service secret | From env TOLLARA_SERVICE_SECRET, or service_secret=... |
Required (Usage HMAC + Core response verification) |
Progress / completion still use the full progress_url / callback_url strings from the gateway (including query params).
Usage report (§3): JSON body includes an ISO-8601 timestamp; X-Tollara-Timestamp is Unix epoch seconds for signing. For report_usage_at, pass timestamp as epoch seconds (or omit for “now”); values above 1e11 are treated as milliseconds and converted.
Constructor arguments override environment variables when both are set.
Environment variables
| Variable | Purpose |
|---|---|
TOLLARA_API_URL |
Optional. Overrides the default production API origin when set (staging, local stacks, tests). |
TOLLARA_SERVICE_ID |
Service UUID if you omit service_id=... (optional) |
TOLLARA_SERVICE_SECRET |
Service secret if you omit service_secret=... (required one way or the other) |
In code, names are also available as TollaraClient.ENV_API_URL, ENV_SERVICE_ID, and ENV_SERVICE_SECRET. The default base URL is TollaraClient.DEFAULT_API_URL.
Requirements
Python 3.10+
Install
pip install tollara-service-sdk
HTTP features (validate, usage, gateway, progress):
pip install tollara-service-sdk[http]
Examples
Verify inbound HMAC (agent backend)
Pass a header map (keys matched case-insensitively) and the raw body the gateway signed (same bytes as in the canonical string). Header names follow TollaraHeaders (X-Tollara-*). Verification defaults to signing version v2 (newer user-context suffix, no quota segment in the signed material).
Preferred: verify and read user context in one step (None if the HMAC is invalid):
from tollara_service_sdk import verify_inbound_context
ctx = verify_inbound_context(service_secret, headers, raw_body)
if ctx is not None:
# ctx.user_id, ctx.plan, ...
...
The former name verify_signature_from_headers_and_get_user_context remains available as an alias of verify_inbound_context.
Or verify and read separately:
from tollara_service_sdk import verify_signature_from_headers, get_user_context
if verify_signature_from_headers(service_secret, headers, raw_body):
ctx = get_user_context(headers)
For full control, build InboundHmacRequest with SignedUserContext and call verify_inbound_hmac(service_secret, req).
Caller / backend HTTP APIs (single client)
from tollara_service_sdk import TollaraClient, CompletionStatus
# Default API origin is production; pass api_url=... or set TOLLARA_API_URL only to override.
# service_secret is required (here or via TOLLARA_SERVICE_SECRET).
client = TollaraClient(
service_id=service_id,
service_secret=service_secret,
)
validation = client.validate_service_key("bearer-token")
# validation.service_key_id — Core key id when present
estimate = client.estimate_usage("bearer-token", 1.0)
if estimate is not None:
allowed = estimate.would_allow
status = estimate.http_status
# JWT usage estimate (unsigned): bearer JWT + internal Core user id + service id
# client.estimate_usage_with_jwt(jwt, core_user_id, service_id, 1.0)
# Gateway invoke: method, service_id, endpoint_id, service_key, optional body=..., async_=...
# client.invoke_service("POST", service_id, endpoint_id, service_key, body="{}", async_=False)
usage_resp = client.report_usage(user_id, service_id, 1.0)
client.send_progress_update(progress_url, request_id, "some processing info", 50)
client.send_completion(
callback_url, request_id, CompletionStatus.COMPLETED, units=1.0, result="some result"
)
status = client.get_request_status(request_id, service_key)
result = client.get_request_result(request_id, service_key)
Tests (from source)
cd sdk-python
pip install -e ".[dev,http]"
pytest
Release (PyPI)
-
Version — Bump
versioninpyproject.tomlunder[project](PEP 440 / SemVer). Each upload must use a new version; PyPI will reject duplicates. -
Verify — Run tests (see above). Optionally run from a clean tree.
-
Build distributions — Install tooling if needed (
pip install build twine), then fromsdk-python:python -m build
This creates
dist/*.whlanddist/*.tar.gz. -
Check —
twine check dist/* -
Upload — Use PyPI (or Test PyPI for a dry run):
twine upload dist/*
Configure credentials via
~/.pypirc, environment variables, or a trusted publisher / API token as described in PyPI’s publishing docs. -
Tag — Tag the Git commit that matches the released version.
Project metadata (name tollara-service-sdk, license, URLs) lives in pyproject.toml.
The SDK methods shown in this README cover invoke, validate, estimates, usage reporting, and gateway polling flows.
Metadata
Release files for tollara-service-sdk 0.0.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| tollara_service_sdk-0.0.1.tar.gz | 24.6 kB | Without provenance | Details for tollara_service_sdk-0.0.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| tollara_service_sdk-0.0.1-py3-none-any.whl | Python 3 | none | any | Details for tollara_service_sdk-0.0.1-py3-none-any.whl |
Total release size: 47.0 kB
Release files / tollara_service_sdk-0.0.1.tar.gz
| Download URL | tollara_service_sdk-0.0.1.tar.gz |
|---|---|
| Size | 24.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
249fec4196b41d676861dcdcb2ec7f2359643871111861ae0c36321fbd8cc4d4
|
|
BLAKE2b-256 checksum How to use checksums |
001bdf707c0ea2162890864ed54d5f89e809f9814168abc24b17ffd8a489ba54
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.11
|
Release files / tollara_service_sdk-0.0.1-py3-none-any.whl
| Download URL | tollara_service_sdk-0.0.1-py3-none-any.whl |
|---|---|
| Size | 22.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
fb0b6b6d8256e9bf77f299caf943e8997a67adf37f82153b85caa607ef28ce46
|
|
BLAKE2b-256 checksum How to use checksums |
781f59453b03c1f2defa30a7598cc53c1099eef72e34c6249708a888325a8b10
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.11
|
Security for tollara-service-sdk 0.0.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.