Information
- License: Proprietary
- OpenAPI version:
3.1.0
Overview
Antares API 0.2.0
Abschnitt betitelt „Antares API 0.2.0“Stable API contract for Antares. Typesense is a private implementation detail and must never be addressed by browser clients. Materialised customer prices are keyed by price-context fingerprint; a caller receives exactly the one context its signed priceContextToken proves entitlement to, and purchasePrice never leaves the API.
The document covers four disjoint audiences, each with its own credential:
- Widget (
pk_live_…) —/v1/search,/v1/instant,/v1/events,/v1/widget/config. Origin-restricted, quota-counted, rate-limited. Never sees another customer’s price. - Connector (
sk_live_…) —/v1/ingest/**,/v1/orders/**,/v1/connector/config,/v1/connect/disconnect. CarriesX-Antares-Environment-Fingerprinton every request. - Panel (service token and actor JWS together) — the whole
/v1/admin/**surface. Neither credential is sufficient alone; see theServiceTokenandActorJWSschemes. - Unauthenticated —
/healthz,/v1/connect/handshake(the pairing code is the only thing it hands out) and/v1/stripe/webhook(verified by Stripe’s own signature).
Every error response is application/problem+json and carries a code from the closed
registry in docs/specs/errors.md. type is always
https://api.antares.commergy.de/problems/{code}. Each response below names the exact
codes it can return.
Authentication
Abschnitt betitelt „Authentication“PublicBearer
Abschnitt betitelt „PublicBearer“Public channel key. Resolves exactly one channel and is restricted by that channel’s allowed origins, the organization’s quota and a per-key rate limit. It is embedded in page source by design and therefore proves nothing beyond “this channel exists”: every response shaped for it goes through the include-allow-list, so no margin input and no unauthorised price context can leave through it.
Security scheme type: http
Bearer format: pk_live_…
SecretBearer
Abschnitt betitelt „SecretBearer“Secret shop key held only by the connector. Authorises ingest, orders, connector configuration and disconnect for one shop. Every request additionally carries X-Antares-Environment-Fingerprint, so a database clone that copied the key still cannot write to the production index. Stored as a lookup hash plus a verifier hash; the plaintext exists once, at connect.
Security scheme type: http
Bearer format: sk_live_…
ConnectPollToken
Abschnitt betitelt „ConnectPollToken“Opaque handle returned by POST /v1/connect/handshake, scoped to that one pairing and valid for the pairing’s ten-minute lifetime. It authorises nothing except polling and collecting the credentials of its own pairing. It travels in a header rather than the query string so it cannot be captured by access logs or referrers.
Security scheme type: apiKey
Header parameter name: X-Antares-Poll-Token
ServiceToken
Abschnitt betitelt „ServiceToken“The panel deployment’s service token, looked up by hash in api_keys with kind = 'service'.
It is a transport credential and nothing else. It proves that the request came from our panel deployment rather than from the open internet. It carries no authority over any organization, addresses no tenant and grants no role. A stolen service token on its own reaches every /v1/admin route and is refused by every one of them, because no organization can be resolved without an actor.
Security scheme type: http
Bearer format: svc_live_…
ActorJWS
Abschnitt betitelt „ActorJWS“A compact JWS minted by better-auth for the signed-in panel user, verified against the panel’s JWKS ({PANEL_URL}/api/auth/jwks, cached 10 minutes, key selected by kid).
Claims: sub (better-auth user id), org (the active organization id, mapped to public.organizations.id through the auth_organizations bridge), role (owner | admin | viewer | staff), imp (the impersonating staff user id, optional) and exp (at most 10 minutes out).
It proves who is acting and for which tenant, and nothing about the network path. A stolen actor token reaches no Antares host, because the service token it must travel with is never in a browser.
Both credentials are required together on every /v1/admin operation and are resolved by one middleware before any handler runs. The role matrix is: viewer = every GET; admin = every GET plus every mutation except billing and key rotation; owner = everything in the organization; staff = additionally /v1/admin/internal/** and impersonation.
Security scheme type: apiKey
Header parameter name: X-Antares-Actor