Architecture

A Wakapp is a third-party application integrated with the WakaStart platform. This chapter gives the full map of the territory before diving into the details.

Why this step

Before writing a single line of integration code, you need to understand how the entities fit together and which services expose which boundaries. A common mistake is to treat the platform as a plain REST CRUD, when it actually carries a strict multi-tenant hierarchy on which all data isolation depends.

Multi-tenant hierarchy

WakaStart organizes entities top to bottom:

textCopy
Partner
  └── App  ←── the Wakapp connects here
        └── Network  (1 realm Keycloak)
              └── Customer
                    ├── User
                    └── Team

Golden rule: all data belongs to a Customer. Isolation is enforced at the query level (Prisma filters) — never through separate databases.

Where the WakaApp sits in the ecosystem

textCopy
                ┌──────────────────────────────────────────┐
                │          PLATEFORME WAKASTART            │
                │                                          │
  ┌──────────┐  │   ┌──────────────┐    ┌──────────────┐   │
  │          │  │   │ API Discovery │    │   Keycloak   │   │
  │  Wakapp  ├──┼──►│  pré-auth     │───►│  OAuth2 OIDC │   │
  │(frontend)│  │   └──────────────┘    └──────┬───────┘   │
  │          │◄─┼──────────────────────────────┘ (PKCE)    │
  │          │  │                                          │
  │          │  │   ┌──────────────────────────────────┐   │
  │          ├──┼──►│  API d'enrichissement /auth/enrich│   │
  │          │  │   └──────────────────────────────────┘   │
  │          │  │                                          │
  │          │  │   ┌──────────────────────────────────┐   │
  │          ├──┼──►│  API publique  /api/...           │   │
  │          │  │   │  CRUD multi-tenant + autorisations│   │
  │          │  │   └──────────────────────────────────┘   │
  └──────────┘  └──────────────────────────────────────────┘

Key points:

• The Discovery API is consumed before authentication to obtain the Keycloak login URL (start-login).
• The /api/auth/enrich endpoint is publicly exposed: any Wakapp can call it after receiving a Keycloak access_token to obtain an enriched wakaToken.
• The public API is the single entry point for all business operations post-auth.

The two public APIs consumed by a Wakapp

The canonical URLs are documented in Environments. No other internal URL can be consumed from a Wakapp.

Stack on the Wakastart side vs. the WakaApp side

Two access modes

API keys entirely replace the Bearer+enriched pair: the public API rebuilds the user context from the key.

Communication flow (overview)

textCopy
1. [PREAAUTH]  Wakapp → API Discovery  : POST /discover/start-login
                                          → URL Keycloak retournée
                Wakapp → Keycloak       : redirect navigateur (PKCE)
                Keycloak → Wakapp       : redirect avec code d'autorisation

2. [EXCHANGE]  Wakapp → Keycloak       : POST /token (code + verifier)
                Keycloak → Wakapp       : access_token + refresh_token

3. [ENRICH]    Wakapp → API publique   : POST /api/auth/enrich (Bearer)
                                          → wakaToken enrichi retourné

4. [PROFILE]   Wakapp → API publique   : GET /api/me
                                          (Bearer + x-enriched-token)
                                          → profil + rôles + appRights

5. [API CALLS] Wakapp → API publique   : GET|POST|PATCH|DELETE /api/...
                                          → données métier paginées

Best practices

• Store tokens in HttpOnly cookies (never in localStorage).
• Use WIDs in your URLs and logs — UUIDs are internal.
• Never inspect or verify the signature of the x-enriched-token on the Wakapp side: delegate to POST /api/token/authorize for any authorization decision.
• Respect the hierarchy in your requests: a CustomerAdmin cannot access another Customer's data.

Learn more

• Discovery — Identifying the user: the first call before auth
• Authentication — OAuth2 PKCE: the full flow
• Using the API: headers, pagination, multi-tenant