SDK overview

tollara.ai publishes official service SDKs for JavaScript/TypeScript, Java, Python, and .NET (C#). They share the same platform contract: verify inbound gateway HMAC, call Core and the usage service with correct signing, invoke through the gateway (sync or async), and report progress/completion using the URLs the platform returns.

Languages

Per-language configuration tables, install commands, and API naming live on each SDK page (aligned with the READMEs in the tollara-sdk monorepo and the copies under docs-sdk/ in this repository).

One-line installs for pinned versions: Install by language.

What every SDK covers

  • Inbound gateway HMAC — Verify the gateway signed the raw body; read user context from X-Tollara-* headers. Current SDKs default to signing v2 (user-context material without a quota segment); follow each README for the exact helper names.
  • Service key validate — Core validate path; verify Core response HMAC when signature headers are present. Successful responses can include a service key row id (see platform §2.1).
  • Usage pre-flight — Service-key estimate (same trust model as validate, signed responses when headers are present) and, where supported, JWT estimate (unsigned Core response).
  • Gateway invoke — Sync or async; Bearer uses the service API key string. Async responses include request id and full progress / callback URLs.
  • Usage reporting — Report billed units; canonical signing uses the JSON body plus timestamp rules documented per SDK (body timestamp vs header epoch seconds where applicable).
  • Usage records — For services that report their own usage, keep your own logs with the tollara.ai request id where available, your internal request id, subscriber or key reference, units, timestamp, endpoint, and usage response. Keep them for at least 24 months for support and reconciliation.
  • Progress and completion — POST to the full platform-provided URLs (including query parameters). Async completion status values are uppercase COMPLETED / FAILED.
  • Async polling — Poll gateway job status (and result where exposed) with the service key.

Recommended client

Each language exposes an TollaraClient (or TollaraClient.Create on .NET) configured with one API origin, optional service id, and a required service secret for outbound signing and Core response verification. Environment variables are supported consistently (TOLLARA_API_URL, TOLLARA_SERVICE_ID, TOLLARA_SERVICE_SECRET); defaults target production https://api.tollara.ai unless overridden.

HMAC and API details

The canonical HMAC specification, test vectors, and release changelogs live in the tollara-sdk repository. This site summarizes behavior developers rely on; for byte-exact signing rules and edge cases, use the monorepo docs and the per-language READMEs.