Core API
The core service manages services, keys, and subscriptions. For SDK and integration use, the main endpoint is service key validation.
Validate service key
POST {coreServiceUrl}/api/v1/service-keys/validate (or /core/api/v1/service-keys/validate when deployed with an ECS path prefix).
Request body: { "serviceKey", "serviceId", "serviceSecret" }. On success the JSON body includes valid, userId, serviceId, plan, roles, validationSchemaVersion (currently 2), subscriptionActive, and when the caller is a subscriber (not the bare owner path) optional fields billingModelType, measurementType, and unitLabel — aligned with invoke-context validation and gateway headers (without a numeric quota field). The response is signed with HMAC in X-Tollara-Signature and X-Tollara-Timestamp; verify using HMAC(responseBody + timestamp, serviceSecret).
The SDK provides a validateServiceKey helper that calls this endpoint and verifies the response HMAC. See SDK overview.
Usage estimate (JWT)
POST {coreServiceUrl}/api/v1/billing/usage/estimate (or /core/api/v1/... with ECS prefix). Requires Authorization: Bearer for the user (or an authorized service). Body: internal userId (UUID), serviceId, estimatedUnits (positive). Typical statuses: 200 allowed, 403 insufficient credits or forbidden, 429 would exceed cap.
The JSON body includes wouldAllow (matches whether this chunk would get a 200), billingModelType / measurementType / unitLabel, legacy flags sufficientCredits and wouldExceedCap, and a breakdown object with calculator-style fields for subscription/postpaid (and a synthetic breakdown for prepaid) so backends can plan long-running work.
Usage estimate (service key)
POST {coreServiceUrl}/api/v1/service-keys/estimate-usage (same path prefix rules as validate). No Bearer. Body: serviceKey, optional serviceId, optional serviceSecret, estimatedUnits. The signed JSON matches the JWT estimate fields (wouldAllow, breakdown, etc.) plus estimateSchemaVersion and timestamp; verify X-Tollara-Signature over the exact response body string concatenated with the timestamp digit string, using serviceSecret, same as validate.
Other endpoints
The core service also exposes service CRUD, billing, and gateway invoke-context endpoints for the dashboard and internal use. For public SDK/docs, validation is the primary integration point.
