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.
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/
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/
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/
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.
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.
products/cca. CCA-Release YYYY-R, Regex-Constraint Pflicht. Versions-Schlüssel des Gateways für CCA-Installationen.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.boa-api/v1.0/…), im Payload oder gar nicht.3 · Beispiele
| URL | Bedeutung |
|---|---|
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.
| Alt | Neu | |
|---|---|---|
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
Immer {caller}/{service}/…. Default-Deny: was nicht explizit geroutet ist, ist nicht erreichbar.
Offene Regex-Segmente DARF NICHT
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
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
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:
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:
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 Host | Default-Umgebung der VU (ohne Suffix) |
|---|---|
| api · api-pre | Produktiv-Umgebung der VU (api-pre = Prod-Staging, gleiche VU-Ziele) |
| api-fachtest · api-fachtest-pre | Test-Umgebung der VU (Mapping in forward.d/fachtest) |
Services – unsere (kein target)
| Slug | Bemerkung |
|---|---|
| soagfx | SOAP; VIG, Generali, ERGO, Riskine |
| soaomdsx gfweitergabe | Generali |
| cads cads-rest | SOAP / REST, getrennte Services |
| gfapi | nur api/v2.0/*, api/makler/v2.0/* |
| boa-api | eigene Version v1.0 im Pfad |
| accounts | OVB Self-Service |
| kooperation | VIG Cooperative Processing (/partners/vig/kooperation/{donau|wstv}/…, Marke im Pfad) |
| autopreisspiegel | CCA |
| scim | Entra-Provisioning: /customers/{org}/scim/ bzw. /partners/{org}/scim/ – Route mappt {org} fest auf die Entra-Tenant-Id; Entra ist Transport, kein Caller |
| userabgleich | Generali, VIG |
| omds3engine | Riskine / BoaBot – ersetzt Catch-All |
| wrka | ÖAMTC Weltreise-Krankenschutz |
| eop-callback | UNIQA Easy Option Plus |
| esign deeplink omds3-bestand | Maklersoftware / Kunden; heute auf www |
Services – VU (mit target)
| omds3 | Pass-Through über tis.partner.*Integration |
| evpconnect | Generali EVP-Connect |