Asteri's public API should be versioned, resource-first, and decoupled from internal tRPC.
The public contract needs to be stable for external teams, boring to integrate with, and strict about tenant boundaries. That means REST-first resources, durable DTOs, scoped keys, and explicit change management.
Stable DTOs
External developers should never depend on internal tRPC procedure shapes. A public contract belongs behind versioned routes such as /api/public/v1.
Org-scoped by default
Every request should be pinned to one organization context, with explicit scope checks and audit logging on every write path.
Least privilege
API keys should remain narrow, expiring, rate-limited, and environment-specific. OAuth comes after the server-to-server model is solid.
Start with the operational backbone that outside systems actually need. Resist the urge to publish the entire internal surface area on day one.
Customer identity, contact points, tags, and activity history for field-service operations.
Scheduling, assignment, completion lifecycle, and downstream operational triggers.
Quote creation, approval flows, acceptance events, and revenue transition states.
Billing state, payment collection hooks, and accounting-system handoff.
Collected payments, invoice linkage, payment methods, and collection-state visibility.
Service catalog visibility for pricing, duration, and booking-facing configuration.
Uploaded file records, MIME metadata, processing status, and storage-bucket context.
Signed event delivery with retries, delivery history, secret rotation, and replay-oriented operations.
Scoped keys, expirations, and rate limits already live inside the Asteri security center.
Generated fetch-based client package aligned with the public OpenAPI contract.
Ship the API program in layers.
Layer 1: scoped API keys for server-to-server integrations and internal platforms.
Layer 2: OAuth clients for partner apps once consent, review, and app analytics exist.
Layer 3: SDKs, app marketplace, and changelog subscriptions once contract stability is proven.
API key access is now part of the preview contract.
Public preview routes accept either an authenticated session/bearer token or a scoped API key sent viax-api-key. Every request still requires an explicitx-organization-id.
curl -X GET \
http://localhost:3000/api/public/v1/customers \
-H "x-api-key: ast_live_your_key" \
-H "x-organization-id: ${ORG_ID}"Credentials are invalid or expired.
This usually means the request is missing x-api-key, the key is inactive or expired, or bearer auth is malformed.
Check the key value, expiry, and whether the request is also sending the correct x-organization-id.
The caller lacks the required scope.
Preview routes enforce narrow scopes like read:customers and write:estimates.
If you receive a missing-scope response, update the key in Security settings or switch to the correct organization.
Honor the limit window before retrying.
Preview API keys can be limited per minute and per day. When you exceed that budget, the response includes a limit window and Retry-After.
Back off worker concurrency, avoid blind replay loops, and only retry after the returned window has reset.
OpenAPI preview
The public contract now emits an OpenAPI document generated from the same source that powers the reference index and developer search.