.NET (C#) SDK

NuGet package Tollara.ServiceSdk — verify HMAC, validate service keys, usage pre-flight (service-key and JWT), gateway invoke, report usage, progress and completion, and poll job status on the gateway. Full contract, changelog, and examples: SDK repo README (sdk-dotnet).

Install

dotnet add package Tollara.ServiceSdk

Contract E2E and install docs pin version 0.0.1. Published package: NuGet — Tollara.ServiceSdk. Pin a version in CI or in Install by language when you need a reproducible build.

Configuration

TollaraClient.Create uses built-in defaults for production. Override the API origin for non-production or private deployments via ApiUrl on TollaraClientOptions and/or the environment variable TOLLARA_API_URL. Optional TOLLARA_SERVICE_ID, required TOLLARA_SERVICE_SECRET (or constructor options). Legacy TOLLARA_AGENT_ID / TOLLARA_AGENT_SECRET are still read if the SERVICE_* variables are unset.

For async flows, callers poll the gateway progressUrl for status. Service backends send progress/completion using the full usage URLs returned by the platform (including query params).

HMAC (summary)

  • Usage service and signed Core JSON responses: canonical string = bodyJsonString + timestamp (no separator); X-Tollara-Timestamp is Unix epoch seconds. For report, the JSON body's timestamp is an ISO-8601 instant. Then Base64(HMAC-SHA256(...)). Helpers: Hmac.CalculateHmacWithTimestamp / ValidateHmacWithTimestamp.
  • JWT usage estimate — not HMAC-signed; do not expect signature headers.
  • Gateway → service inbound — canonical = payload + timestamp + userContextString. Verification defaults to v2 via BuildGatewayUserContextStringV2.
  • Async completion — JSON status must be uppercase COMPLETED or FAILED; use CompletionStatus and ToApiString() for payloads.

Main entry points

  • TollaraClient.Create / async methods — report usage, estimates (service key and JWT), invoke, polling
  • Verifier.VerifyInboundHmacAndGetUserContext, VerifySignatureFromHeaders, InboundHmacRequest with SigningVersion: "2" recommended

See also