api.togethercca.com – Routen-Format

⚠️ Not yet reviewed KI-Vorschlag als Diskussionsgrundlage, keine Entscheidung · Cheat Sheet für Entwickler · Stand: Proposal api-gateway-route-format (Draft) · Gilt für alle Maschinen-Schnittstellen über die TOGETHER-Plattform, nicht für Routen der WebApp.

1 · Schritt 1: Namensraum wählen – wer ruft?

Jede Route liegt in genau einem von vier Namensräumen. Das ist die erste Frage bei jeder neuen Route. In dieser Reihenfolge prüfen, der erste Treffer gilt.

1/products/

Der Caller ist unser Produkt – egal, wer es entwickelt.

Produkt schlägt Partner. BoaBot wird von Riskine entwickelt, ist aber unser Produkt → /products/boabot/

hier cca boa-api boabot

nicht hier Riskine mit eigenen Produkten → /partners/riskine/

2/partners/

Der Caller ist eine VU oder ein Integrations-Partner mit eigener Plattform-Anbindung.

System-Kontext: das fremde System selbst ist der Akteur, kein Makler-Principal (client_credentials / IP, oder delegation_scope: together:all-users). Generali ändert einen Geschäftsfall, VIG holt CADS-Daten ab. Kriterium: Vorschlag

hier vig generali uniqa ergo riskine

nicht hier Software und Portale, die unsere Kunden verwenden → /3rd-party/

3/customers/

Der Caller ist eine Kundenorganisation, die für sich selbst ruft.

Makler-Büro-Kontext, eine Organisation: der Client ist an die Organisation bzw. feste MaklerIds gebunden (delegation_scope: maklerid:…, Scope auf eigene Vermittler, oder eigene Software der Organisation). Kriterium: Vorschlag

hier oeamtc greco ovb efs versfinanz oebv

nicht hier Software, die viele Büros nutzen → /3rd-party/ · VUs → /partners/

4/3rd-party/

Der Caller ist Fremdsoftware oder ein Portal, das unsere Kunden einsetzen.

User-Kontext, viele Organisationen: User-Token (authorization_code); hinter einem Client stehen viele Makler-Büros, die Organisation ergibt sich erst aus dem eingeloggten Makler. Caller = App, Organisation = zweite Dimension aus dem Token. Namensraum: Vorschlag

hier vers-admin-m onlineordner basic-systems cheggnet durchblicker

nicht hier unsere Produkte, auch wenn fremdentwickelt → /products/ · Software, die nur für eine Organisation gebaut ist (FB-Research für SLS) → /customers/sls

Regel Autorenschaft ist irrelevant – entscheidend ist, an wen der Zugang gebunden ist. BoaBot (von Riskine entwickelt) → /products/; FB-Research-Anbindung für SLS → /customers/sls. Erst ein eigener Client für mehrere Kunden macht aus FB-Research /3rd-party/fb-research.

Ausnahme Riskine ruft SOAGFX für eigene Produkte und für BoaBot über /partners/riskine/soagfx – keine getrennte /products/boabot/soagfx-Route nötig.

2 · Schritt 2: Grammatik je Namensraum

Die Namensräume sind Literale, kein variables Segment. Alle übrigen Segmente sind in allen Formen gleich – mit einer Ausnahme: unter /products/cca/ kommt der Release-Key dazu. Das Gateway schreibt kein Versions-Segment vor – ob und wie ein Service seinen Contract versioniert, entscheidet der Service.

/partners/Literal {caller}wer ruft / {target}Ziel-VU (optional) -{targetEnv}nur bei Abweichung / {service}Contract-Name / {**path}Rest an Downstream
/customers/Literal {caller}wer ruft / {target}Ziel-VU (optional) -{targetEnv}nur bei Abweichung / {service}Contract-Name / {**path}Rest an Downstream
/3rd-party/Literal {caller}wer ruft / {target}Ziel-VU (optional) -{targetEnv}nur bei Abweichung / {service}Contract-Name / {**path}Rest an Downstream
/products/Literal {caller}≠ cca / {target}Ziel-VU (optional) -{targetEnv}nur bei Abweichung / {service}Contract-Name / {**path}Rest an Downstream
/products/Literal ccaLiteral / {release}CCA-Release YYYY-R / {target}Ziel-VU (optional) -{targetEnv}nur bei Abweichung / {service}Contract-Name / {**path}Rest an Downstream

Hosts: api.togethercca.com (Prod) · api-pre.togethercca.com (Prod-Staging, verifiziert die Prod-Routen) · api-fachtest.togethercca.com / api-fachtest-pre.togethercca.com (Fachtest) – unsere Umgebung kommt nur über den Host, nie über den Pfad.

/partners/ …Literal – einer der vier Namensräume aus Schritt 1.
callerSlug aus Registry. Muss zur Token-Identität passen (Tenant-Binding, erzwungen).
releaseNur products/cca. CCA-Release YYYY-R, Regex-Constraint Pflicht. Versions-Schlüssel des Gateways für CCA-Installationen.
target-envVorhanden ⇔ Service gehört einer VU (Pass-Through). Fehlt ⇔ unser Service.
Ohne Suffix = Default-Umgebung der VU. Welche das ist, folgt aus unserer Umgebung: api / api-pre → VU-Prod, api-fachtest / api-fachtest-pre → VU-Test (Mapping in forward.d/{env}). Suffix -maint · -test nur, wenn ein Caller bewusst davon abweicht.
serviceContract-Name, kleingeschrieben, aus Registry.
pathWird 1:1 (ggf. mit Prefix-Mapping) an den Downstream weitergereicht. Eine Contract-Version ist optional und Sache des Service – im Pfad (boa-api/v1.0/…), im Payload oder gar nicht.
gestrichelt= optionales Segment

3 · Beispiele

URLBedeutung
https://api.togethercca.com/partners/vig/soagfx/…
VIG ruft unseren SOAGFX (kein target → eigener Service)
https://api.togethercca.com/partners/generali/gfweitergabe/…
Generali ruft unsere GF-Weitergabe
https://api.togethercca.com/partners/vig/kooperation/donau/…
VIG Cooperative Processing. Die Marke (Donau/WSTV) ist Teil des Service-Pfads, kein target – kooperation ist unser Service, ein Client für beide Marken.
https://api.togethercca.com/customers/oeamtc/generali/omds3/…
ÖAMTC → Generali OMDS3 über unseren Integration-Service (Pass-Through)
https://api.togethercca.com/customers/oeamtc/generali-maint/evpconnect/…
ÖAMTC → Generali EVP-Connect, Wartungsumgebung der Generali – bewusste Abweichung vom Default. Env hängt am Target, nicht am Service.
https://api.togethercca.com/customers/efs/boa-api/v1.0/kfz/valuelists
EFS ruft die BoaApi. EFS-Token auf /customers/versfinanz/… → 403 (Tenant-Binding).
https://api.togethercca.com/3rd-party/vers-admin-m/boa-api/v1.0/kfz/…
Maklersoftware ruft die BoaApi für den eingeloggten Makler – ein Pfad für alle Büros, die Vers-Admin nutzen.
https://api.togethercca.com/customers/oeamtc/scim/Users
Entra-Provisioning des ÖAMTC. Entra ist Transport, nicht Caller; die Route mappt oeamtc fest auf die Entra-Tenant-Id → das Gateway erzwingt den Mandanten.
https://api.togethercca.com/customers/ovb/accounts/…
OVB Self-Service
https://api.togethercca.com/products/cca/2026-8/generali/omds3/…
CCA Release 2026-8 → Generali OMDS3. Der Release-Key ist der Versions-Schlüssel des Gateways.
https://api.togethercca.com/products/cca/2026-8/autopreisspiegel/…
CCA Release 2026-8 → unser Autopreisspiegel
https://api.togethercca.com/products/boa-api/uniqa/omds3/…
BoaApi → UNIQA OMDS3 (BoaBot geht künftig über die BoaApi)
https://api.togethercca.com/products/boabot/generali/omds3/…
BoaBot → Generali OMDS3. Unser Produkt, von Riskine entwickelt → products, nicht partners.
https://api.togethercca.com/partners/riskine/soagfx/…
Riskine ruft SOAGFX – für eigene Produkte und für BoaBot (definierte Ausnahme)
https://api.togethercca.com/3rd-party/cheggnet/donau/omds3/kfz
Vergleichsportal → Donau Kfz-Tarif. Caller = Portal; die Makler-Organisation kommt aus dem User-Token.

Das Gateway schreibt kein Versions-Segment vor. Wo ein Service selbst versioniert (z.B. boa-api/v1.0/…), ist das Teil des Service-Pfads und bleibt unverändert.

4 · Alt → Neu

Links: was heute auf www.servicebytogether.at / b2b.servicebytogether.at (Helicon) oder als Legacy-Route am Gateway exponiert ist. Rechts: Zielformat. Alte Pfade bleiben als deprecated Alias bestehen, solange ein unterstütztes Release sie nutzt.

AltNeu
b2b.servicebytogether.at/axis2/services/SOAGFX_2_0
Helicon, anonym am Edge, interner Axis2-Pfad öffentlich
→
/partners/vig/soagfx/…
Scope-Policy + Tenant-Binding am Gateway
b2b.servicebytogether.at/GFWeitergabe/…
Helicon
→
/partners/generali/gfweitergabe/…
b2b.servicebytogether.at/SOAOMDSX/…
Helicon
→
/partners/generali/soaomdsx/…
www.servicebytogether.at/omds3services/donau/kfz/
Helicon → tis.gf.omds3.vigong; OMDS3-Portale (cheggnet, durchblicker)
→
/3rd-party/cheggnet/donau/omds3/kfz
Caller = Portal → Rate-Limit und Telemetrie pro Portal und pro Makler-Büro
www.servicebytogether.at/omds3Services/uniqa/kfz/…
Helicon → tis.partner.uniqaIntegration/omds3-forwarder; Caller: CCA-Installationen
→
/products/cca/2026-8/uniqa/omds3/kfz/…
Release-Key als Versions-Schlüssel; Default-Route ist Template über alle Releases
www.servicebytogether.at/tis.partner.vigIntegration/api/kooperation/donau/…
Helicon, Deploy-Name öffentlich
→
/partners/vig/kooperation/donau/…
www.servicebytogether.at/tis.gf.boaapi/api/v1.0/kfz/valuelists
Helicon, Deploy-Name öffentlich
→
/customers/efs/boa-api/v1.0/kfz/valuelists
eine Regex-Route für efs|versfinanz statt Kopie pro Tenant
www.servicebytogether.at/cads.extern/oauth
Helicon → Wildfly
→
/partners/basic-systems/cads
api.togethercca.com/services/scim/{tenantId}/Users
Gateway-Legacy; Tenant-Id kommt ungeprüft vom Caller
→
/customers/oeamtc/scim/Users
Route mappt Slug → Tenant-Id; Secret-Check bleibt downstream
api.togethercca.com/services/autopreisspiegel/…
Gateway-Legacy ohne Caller-Segment
→
/products/cca/2026-8/autopreisspiegel/…
api.togethercca.com/omds3services/{vu}/sachprivat
Gateway-Legacy (Vigong)
→
/products/cca/2026-8/donau/omds3/sachprivat
api.togethercca.com/customers/{[a-zA-Z]+}/cads
Gateway heute: offenes Regex-Segment, Tenant nicht erzwungen
→
/customers/oeamtc/cads
Caller-Slug aus Registry, an Token gebunden
api.togethercca.com/partner/{vu:regex(donau|wstv)}/kooperation/…
Gateway heute: Marke an Stelle des Callers; ein Client (vig.cooperativeProcessing) für beide
→
/partners/vig/kooperation/wstv/…

5 · Regeln

Tenant-Binding MUSS

caller ist kein Namensraum, sondern wird gegen die Token-Identität (Client-Id / Tenant-Claim) geprüft. Gleicher Scope reicht nicht. Das Segment geht als Header (X-Tis-Tenant) an den Downstream.

Kein Catch-All unter caller DARF NICHT

/partners/riskine/{**remainder}

Immer {caller}/{service}/…. Default-Deny: was nicht explizit geroutet ist, ist nicht erreichbar.

Offene Regex-Segmente DARF NICHT

/customers/{x:regex([a-zA-Z]+)}/gfapi

Nur Slugs aus der Registry, ggf. als geschlossene Alternation: {customer:regex(^(efs|versfinanz)$)}.

scope oder anonymous MUSS

Jede Route hat scope – oder ein explizites anonymous mit Begründung im Kommentar. health einmal pro Backend, nicht pro Tenant.

Umgebung am Service DARF NICHT

/customers/oeamtc/generali/omds3-maint

Die Umgebung ist eine Eigenschaft der VU → generali-maint. Ohne Suffix gilt die Default-Umgebung der VU, die sich aus unserer Umgebung ergibt. Unsere Umgebung kommt nur über den Host.

Contract-Version: Sache des Service KANN

/customers/efs/boa-api/v1.0/kfz/…

Das Gateway erzwingt kein Versions-Segment und versioniert nicht automatisch. Ob und wie ein Service versioniert (Pfad, Payload, gar nicht), liegt beim Service – bei VU-Services nicht einmal in unserer Hand. Eine Service-Version ist Teil von path.

Release-Key: Template + Override MUSS

Default-Route ist ein Template – ein neues CCA-Release braucht keine Gateway-Änderung:

{release:regex(^\d{4}-\d{1,2}$)}

Override-Routen (order -1) nur für Kompatibilität nach einem VU-Breaking-Change, nie für Fachlogik. Jede trägt Ticket, Grund und Sunset:

{release:regex(^(2025-.*|2026-[1-8])$)}

Gateway routet, übersetzt nicht

Hinter einer Override-Route steht ein eingefrorenes Parallel-Deployment des Integration-Service (z.B. tis.partner.generaliIntegration-2026-8), das den alten VU-Contract bedient. Kein Compat-Code rückwärts in den laufenden Service.

Nur api.togethercca.com

Maschinen-Routen ausschließlich am Gateway. Auf www / b2b werden keine neuen API-Routen angelegt. Interne Deploy-Namen (tis.partner.*, tis.gf.*) erscheinen nie in öffentlichen URLs.

Legacy = Alias mit Sunset deprecated

/partner/* (Singular, heute produktiv), /services/*, /omds3services/* und direkte App-Namen bleiben als Alias auf dasselbe Backend, mit # deprecated + Sunset-Kriterium im Kommentar. Abbau erst bei nachweislich null Nutzung (Route-Telemetrie).

Ein Slug, überall derselbe

Der Registry-Slug wird einheitlich in Route, Scope-Name, Client-Id, Log-Dimension und Rate-Limit-Key verwendet. Zu bereinigen: gli.*-Scopes bei Route generali, soagfx.wstv/soagfx.don bei Route vig.

6 · Registry

Vollständige Registry mit Identity-Clients, Scopes, Backends und Bereinigungsliste: api-gateway-route-registry. Tenant-Binding über Client-Claim tis_tenant in tis.identity.

Caller

/products/cca boa-api boabot
/partners/vig generali ergo uniqa riskine
/customers/oeamtc greco ovb efs efm versfinanz sls wefox aon arisecur avag cbn igv dvm afb gundo pth sivag oebv mercedes toyota-im rci sepp-schinner
/3rd-party/basic-systems vers-admin-a vers-admin-m onlineordner proagent varias vera insureit finova novumrgi krankenprofi courtagecontrol servers insurapp authentic cheggnet durchblicker check24 kapdion promakler

Targets (VU-Systeme)

uniqa generali donau wstv allianz hdi grawe vav zuerich wuestenrot muki merkur

Env-Suffix (nur bei Abweichung vom Default): -maint -test

Unser HostDefault-Umgebung der VU (ohne Suffix)
api · api-preProduktiv-Umgebung der VU (api-pre = Prod-Staging, gleiche VU-Ziele)
api-fachtest · api-fachtest-preTest-Umgebung der VU (Mapping in forward.d/fachtest)

Services – unsere (kein target)

SlugBemerkung
soagfxSOAP; VIG, Generali, ERGO, Riskine
soaomdsx gfweitergabeGenerali
cads cads-restSOAP / REST, getrennte Services
gfapinur api/v2.0/*, api/makler/v2.0/*
boa-apieigene Version v1.0 im Pfad
accountsOVB Self-Service
kooperationVIG Cooperative Processing (/partners/vig/kooperation/{donau|wstv}/…, Marke im Pfad)
autopreisspiegelCCA
scimEntra-Provisioning: /customers/{org}/scim/ bzw. /partners/{org}/scim/ – Route mappt {org} fest auf die Entra-Tenant-Id; Entra ist Transport, kein Caller
userabgleichGenerali, VIG
omds3engineRiskine / BoaBot – ersetzt Catch-All
wrkaÖAMTC Weltreise-Krankenschutz
eop-callbackUNIQA Easy Option Plus
esign deeplink omds3-bestandMaklersoftware / Kunden; heute auf www

Services – VU (mit target)

omds3Pass-Through über tis.partner.*Integration
evpconnectGenerali EVP-Connect