49:T5be, # Environments > 📍 **Where to find this in the UI** — Infra → **Environments** tab (list); click an env for its full dashboard > **An environment = a complete, isolated instance of your app**. ## Main fields of an environment | Field | Example | Role | |-------|---------|------| | `env` | `dev` / `prod` / `staging` | Environment type | | `shortname` | `exemple` | Short nickname of the app in this env | | `slug` | `exemple-dev` | Unique identifier of the environment (used in URLs) | | `gitRef` | `main` / `dev` / `feature/X` | Git branch watched by this env | | `gitRefType` | `BRANCH` / `TAG` / `COMMIT` | Type of Git reference | | `autoDeployEnabled` | `true` / `false` | Auto-deploy when a build on this ref succeeds | ## Lifecycle of an env ``` ACTIVE → (pause) → PAUSED → (resume) → ACTIVE ↓ DELETING → (cleanup) → deleted ``` ## The environment dashboard When you click on an environment, you get access to: | Tab | Content | |--------|---------| | **Summary** | Overview (services up, last deploy, health) | | **Services** | List of ServiceInstances with their runtime state | | **Deployments** | History of deployed versions + rollback | | **Configuration** | Variables and secrets of the env | | **Jobs** | Scheduled tasks (cron jobs) | | **Databases** | This env's DatabaseInstances | | **Storage** | This env's StorageBucketInstances | | **URLs** | This env's public URLs | | **Monitoring** | Metrics, centralized logs | 4a:T4b8, # Builds and Deployments — the difference > 📍 **Where to find this in the UI** > - **Builds**: Infra → **Builds** tab > - **Deployments**: Infra → **Environments → {env} → Deployments** This is a distinction that can trip you up: | | Build | Deployment | |--|-------|------------| | **What** | Converts code into a Docker image | Launches an existing image in an environment | | **Level** | App (architecture) | Environment | | **Concerns** | A ServiceDefinition | A ServiceInstance | | **Result** | An image available in the registry | Pods running in an environment | ## Typical workflow 1. You commit code and push to `main` 2. Wakastart **builds**: `main` HEAD → image `:abc123` 3. Once `SUCCEEDED`, in AUTO mode, the image is **deployed** to the environments watching `main` 4. Wakastart applies → pods are updated (rolling update with no downtime) 5. The **Deployment** appears in the env's Deployments tab, with status `IN_PROGRESS` then `SUCCEEDED` ## Deployment modes (DeploymentMode) | Mode | Behavior | |------|--------------| | `AUTO` | Auto-deploy as soon as a build on the watched branch succeeds | | `MANUAL` | You explicitly choose when to deploy (and which image) | 4b:Tba5, # Complete Workflow — Creating an App from Scratch Here is an end-to-end walkthrough to understand how everything fits together. ## Step 1 — Create the App You go into the UI, "New App", you give it a name. Wakastart creates: - The `App` record in the DB - A dedicated space in the registry for your future Docker images - A dedicated space in the secrets vault for your credentials ## Step 2 — Define the Architecture You navigate to **Infra → Architecture**. You create: 1. **A managed Repository** `exemple-backend` (Wakastart creates the repo on GitHub via the `Waka-Start` org) 2. **A ServiceDefinition** `backend` (role: BACK, exposure: PUBLIC, port: 3000, from the `exemple-backend` repo) 3. **A DatabaseDefinition** `primary` (engine: PostgreSQL, defaultMode: IN_CLUSTER) 4. **A StorageBucketDefinition** `medias` (defaultMode: MANAGED) ## Step 3 — Create an environment You create a `dev` environment: - gitRef: `main` - autoDeploy: true → Wakastart creates for this environment: - A dedicated Kubernetes namespace that isolates the env's resources - The DatabaseInstance and StorageBucketInstance matching the Definitions (in-cluster in dev) - The application credentials to access the env's resources - A platform-managed URL `app.dev.exemple.wakastart.app` ## Step 4 — Build and deploy You commit code, you push to `main`. Wakastart: 1. Detects the push via a GitHub webhook 2. Creates a **Build** in PENDING 3. The build moves through BUILDING → PUSHING → SUCCEEDED 4. In AUTO mode → the image is **deployed** to the `dev` env 5. A **Deployment** appears, status PROGRESSING, then SUCCEEDED 6. Your pods are running, your API is accessible at `app.dev.exemple.wakastart.app` ## Step 5 — Promote to prod You create a `prod` environment: - gitRef: `prod` (dedicated branch) - autoDeploy: true - You override your DatabaseInstance: `mode: MANAGED` (managed PostgreSQL, HA + auto backups) - You add a custom domain `exemple.com` → Your app now runs in prod on managed infrastructure, isolated from dev. --- ## Frequently asked questions **"Why is there a Definition / Instance distinction?"** → So that you can define your architecture **once** and duplicate it across multiple environments with local overrides (cheaper plan in dev, more powerful in prod). **"My build failed, where do I look?"** → **Infra → Builds → click on the build**: you see the Docker build logs and the precise error. **"My service won't start, where do I look?"** → **Infra → Environments → {env} → Services → {service}**: **Logs** tab for the container logs, **Deployments** tab to see if the deployment failed. **"How do I rotate my DB credentials?"** → For databases in `MANAGED` mode: rotation is triggered on the cloud provider side. K8s secrets are regenerated and services are redeployed. **"How do I restore a backup?"** → **Infra → Backups**: you see the list of backups, click **Restore** on the one you want. 4c:T34af, # Deployment Best Practices These rules come from incidents encountered on real services. They cover everything that can silently break a deployment: missing config, poorly built Docker image, forgotten DB migrations, misaligned Next.js runtime config, shaky OAuth/Keycloak integration. --- ## 1. Environment variables Each `.env.example` file constitutes a **configuration contract**. It must be exhaustive, self-documented, and kept up to date with every evolution of the project. ### 1.1 Mandatory rules for each variable | Icon | Attribute | Requirement | |---|---|---| | 📝 | Example value | Provide a real, functional example value. No empty placeholder like `xxx` or `changeme`. | | 📌 | Contextual description | Explain in one sentence why this variable is needed for the application to work. | | 🔁 | Cross-service duplicate | If the same value is expected in another microservice (e.g. front AND back), document the duplication, explain why it exists, and state that any change must be propagated to all affected services. | | ✅ / ⚠️ | Required or optional | Clearly state whether the variable is required or optional, and describe the impact of omitting it (degraded behavior, fatal error, disabled feature…). | | 🌐 | URL type | If the value is a URL, specify whether it must be public (accessible from the browser) or private (accessible only from the internal network / K8s pod). | | 🧪 | Dev only | If the variable is only used in dev, state this explicitly and explain why it isn't needed in prod. | | 🔐 | Secret | If reading this value by an unauthorized person poses a risk (data leak, dangerous access — e.g. `DATABASE_URL`, API keys, tokens), mark it as SECRET. | | 🔑 | Encryption / authorization impact | If the variable affects an encryption scheme or an authorization system, document: (1) the services that must share the same value, (2) the risks of changing it (e.g. permanent loss of access to encrypted data), (3) the expected format and the generation command. | ### 1.2 Documentation example ```env # URL of the backend API consumed by the frontend. # TYPE: public URL (accessible from the user's browser). # REQUIRED — without this variable, all API requests fail. # DUPLICATE: This variable corresponds to BACKEND_URL on the backend side. # Changing it here requires updating BACKEND_URL in the backend service. NEXT_PUBLIC_API_URL=https://api.exemple.com # Encryption key for session tokens. # TYPE: SECRET — never commit in plain text nor change without a migration plan. # WARNING: Changing this value invalidates all active tokens. # FORMAT: 32 bytes hex — generate with: openssl rand -hex 32 ENCRYPTION_KEY= ``` ### 1.3 `NEXT_PUBLIC_*` vs runtime variables (Next.js) `NEXT_PUBLIC_*` variables are **compiled at build time** by Next.js and inlined into the JS bundle. They cannot be changed at container runtime. If a URL needs to be configurable without a rebuild (e.g. Keycloak URL, API URL), it must go through the `window.__RUNTIME_CONFIG__` mechanism injected by `docker-entrypoint.sh` (see [section 4](#4-frontend-runtime-config-nextjs)). Explicitly document in each service's `.env.example`: - which variables are compiled at build time (`NEXT_PUBLIC_*`) - which ones are injected at runtime via `window.__RUNTIME_CONFIG__` - in case of overlap between the two mechanisms, which one takes priority and why > ⚠️ Never commit a real `.env` file to the Git repository. Only the `.env.example` (with no real secret values) is versioned. --- ## 2. Dockerfile and Prisma migrations In the absence of advanced CI/CD tooling, any application requiring a database must guarantee that Prisma migrations are applied automatically when the container starts. ### 2.1 Mandatory entrypoint for applications using Prisma The Dockerfile of any backend application using Prisma must delegate startup to an `entrypoint.sh` script. This script applies migrations before starting the main Node.js process. **Typical structure of an `entrypoint.sh`**: ```sh #!/bin/sh set -e echo '[entrypoint] Running Prisma migrations...' npx prisma migrate deploy echo '[entrypoint] Starting application...' exec node dist/main.js ``` **Associated Dockerfile configuration**: ```dockerfile FROM node:20-alpine WORKDIR /app COPY . . RUN npm install --omit=dev RUN npx prisma generate RUN npm run build COPY entrypoint.sh /entrypoint.sh RUN chmod +x /entrypoint.sh ENTRYPOINT ["/entrypoint.sh"] ``` ### 2.2 Pitfalls to avoid - ✅ `prisma` must be listed in `dependencies` (and **not** `devDependencies`) to be available when the production container runs. - 🚨 **Never** use `pnpm prune --prod` without having verified that `prisma`, `prisma generate`, and all required native binaries (`bcrypt`, `multer`…) are in the production `dependencies`. ### 2.3 Optional seed: injecting initial or test data Your service's container is the only entry point to its live database. To **re-inject data** (reference dataset, demo data, or your local environment's test data) into a Wakastart deployment, the right place is the **same `entrypoint.sh`**, **after** migrations are applied and **before** the application starts. The seed must be **controllable via an environment variable**: a container restarts regularly (rollout, scale, crash), so you don't want it to run again on every startup. The variable lets you enable it temporarily on the desired environment (typically dev), then disable it once the data has been injected. **Step 1 — Declare the seed command in `package.json`**: ```json { "prisma": { "seed": "ts-node prisma/seed.ts" } } ``` > `npx prisma db seed` runs the command defined in the `prisma.seed` block. You can also use your own script (`npm run seed`). **Step 2 — Condition the seed in `entrypoint.sh`**: ```sh #!/bin/sh set -e echo '[entrypoint] Running Prisma migrations...' npx prisma migrate deploy # Optional seed — only if RUN_SEED=true if [ "$RUN_SEED" = "true" ]; then echo '[entrypoint] RUN_SEED=true → seeding database...' npx prisma db seed else echo '[entrypoint] RUN_SEED not enabled → skipping seed.' fi echo '[entrypoint] Starting application...' exec node dist/main.js ``` **Step 3 — Control `RUN_SEED` via Wakastart variables**: the variable is defined like any other config var of your service (see [Variables & Secrets](/v1.0/dev/29-vars-secrets)). Set `RUN_SEED=true` on the environment where you want to inject the data (e.g. a dev env), deploy, then **set the variable back to `false`** once the seed has been applied, to avoid it running again on the next restart. **Best practices**: - ✅ The seed script must be **idempotent**: use `upsert` (or a guard "do nothing if the table is already populated") rather than `create`, so it can be replayed without creating duplicates. - ✅ `ts-node` (or whatever tool your seed command uses) must be available at runtime in the image — place it in `dependencies` if you call it at runtime, or compile the seed script along with the rest of the application. --- ## 3. TypeScript and NestJS / Node.js build TypeScript build errors are a frequent cause of silently broken deployments. | Rule | Detail | |---|---| | **`rootDir` required** in `tsconfig.build.json` | Always declare `rootDir: "./src"` to guarantee that the compiled output lands in `dist/main.js` and not `dist/src/main.js`. Without `rootDir`, the output path depends on the resolved module and breaks the container's startup. | | **Avoid imports outside `rootDir`** | Never import from `../package.json` or any path located outside the defined `rootDir`. Such imports cause `tsc` errors and are not accessible inside the production Docker image. | | **`postinstall` scripts with pnpm v10+** | pnpm v10 blocks `postinstall` scripts by default. Explicitly configure `pnpm.onlyBuiltDependencies` in `package.json` to allow the generation of Prisma, bcrypt, and other native dependency binaries. | | **Native dependencies in production** | `multer`, `bcrypt`, and any package required at runtime must be in `dependencies`, not `devDependencies`, even when used through a framework like NestJS. | | **`prisma.config.ts` without `dotenv`** | Do not import `dotenv/config` in `prisma.config.ts`. `dotenv` is not available in the production image, and environment variables are injected by the orchestration system (K8s). | --- ## 4. Frontend runtime config (Next.js) Next.js applications deployed as containers have two configuration sources: `NEXT_PUBLIC_*` variables (compiled at build time) and variables injected at runtime via `window.__RUNTIME_CONFIG__`. Variable names must be strictly aligned between `docker-entrypoint.sh` and the Kubernetes deployment. ### Rules for runtime config - The frontend's `entrypoint.sh` must read variables **exactly as defined in the K8s deployment** (`NEXT_PUBLIC_API_URL`, `KEYCLOAK_PUBLIC_URL`, etc.), and **not** locally invented aliases (`API_URL`, `KEYCLOAK_URL`…). - Any URL that might change depending on the environment **without a rebuild** of the image (e.g. Keycloak URL) must be injected via `window.__RUNTIME_CONFIG__` and **not** read via `process.env.NEXT_PUBLIC_*`. - Document in each service's `.env.example` which variables are compiled at build time (`NEXT_PUBLIC_*`) and which are injected at runtime. - In case of overlap between a `NEXT_PUBLIC_*` variable and a runtime variable, explicitly document which one takes priority and why. > ⚠️ An `entrypoint.sh` that reads nonexistent variables leaves `window.__RUNTIME_CONFIG__` with hardcoded default values (`localhost`, `preprod`…), which is undetectable without logs. --- ## 5. S3 and Object Storage integration S3 adapters must correctly handle endpoint URLs to avoid silent connectivity errors. ### Rules for S3 endpoints - **Never** mechanically prefix `https://` onto an endpoint variable: if the variable already contains the protocol, double-prefixing produces an invalid URL (`https://https://…`) that linters cannot detect. - The adapter must **detect** whether the endpoint already contains a protocol, **parse** the URL to derive the port (`443` for `https`, `80` for `http`), and **not force** the default port `9000` (which is the local MinIO port, not the OVH Object Storage port). - Document in `.env.example` whether the `MINIO_ENDPOINT` / `S3_ENDPOINT` variable should or should not include the protocol, the port, and the path. - Prefer standard S3-style variables such as: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, etc. --- ## 6. Authentication and OAuth / Keycloak flow > See also [Authentication — Concepts & Flow](/v1.0/dev/03-authentication-overview) for the general OAuth flow. The rules below are **concrete pitfalls** encountered on production services. ### 6.1 `redirect_uri` The `redirect_uri` sent in the authorization request must be **strictly identical** to the one used during the server-side code exchange. Any discrepancy causes Keycloak to reject it. The server must use the `redirect_uri` **provided by the client** during the callback, not a hardcoded value. ### 6.2 `sessionStorage` keys All `sessionStorage` keys used in the OAuth flow (`realm`, `client_id`, `state`, `code_verifier`…) must be declared in a **shared constants file** across all involved modules. Scattered string literals are forbidden. ### 6.3 `login_hint` When the user's email is known before redirecting to Keycloak, pass the standard OIDC `login_hint` parameter to pre-fill the Keycloak form and avoid double entry. ### 6.4 Multi-organization (Discovery) If the Discovery API can return multiple accounts for the same email (multiple Keycloak realms), the frontend must display an **organization selection** screen before redirecting. Never blindly take `users[0]` if the response can contain multiple entries. - Check for the presence of users with `users?.length > 0` and **not** with a `found` field that may not exist depending on the API version. - Systematically verify the **exact name** of the identifier field returned by the API (`customer_wid` vs `network_id`, `customer_id` vs `customer_wid`…) and document it in the API contract. ### 6.5 Keycloak URL on the server side The `KEYCLOAK_URL` variable (internal or public URL for server-side calls) must be **explicitly defined** in the K8s configuration. Without it, calls fall back to `localhost:8080` and fail silently. Document in `.env.example` the difference between `KEYCLOAK_URL` (server-side) and `NEXT_PUBLIC_KEYCLOAK_URL` / `KEYCLOAK_PUBLIC_URL` (client-side / runtime). --- ## 7. Prisma migrations (beyond runtime) Database migrations must be managed deterministically and reproducibly across environments. ### Rules for Prisma migrations - The `prisma/migrations/` directory must contain an **initial migration** generated by `prisma migrate dev` that creates the entire schema. Loose SQL scripts not managed by Prisma are not acceptable. - Specific migrations (e.g. FTS index, column additions) must be encapsulated in **dedicated Prisma migrations**, not as standalone SQL files. - `prisma` must be in `dependencies` (not `devDependencies`) so that `prisma migrate deploy` is available in the production image. - `entrypoint.sh` runs `prisma migrate deploy` before any application startup — see [section 2](#2-dockerfile-and-prisma-migrations). - Never import `dotenv/config` in `prisma.config.ts`: environment variables are injected by K8s. 4d:Tbbb, # Hosting Glossary ## General concepts - **PaaS** (Platform as a Service): you code your app, the platform hosts it — it provides the infra, the OS, the runtime, and the deployment pipeline. Opposite: IaaS (you manage the VMs). - **Kubernetes (K8s)**: orchestrator that runs Docker containers on a cluster of servers. Wakastart is built on top of it. - **Pod**: the smallest K8s unit, contains 1+ containers. A ServiceInstance with `replicas: 3` gives 3 pods. - **Cluster**: a set of servers (nodes) running K8s together. Wakastart operates several clusters (one per major environment). - **Namespace**: an isolation boundary within a cluster. Each Wakastart environment has its own dedicated namespace — this is what isolates resources between apps and between environments. ## Images and registry - **Docker image**: a frozen package containing your code + its dependencies + the minimal OS needed to run. Reproducible. - **Registry**: a store for Docker images. Wakastart provides a private registry per app — your images never leave it. - **Tag**: a version name of an image (e.g. `:latest`, `:1.2.3`, `:abc123`). - **Quota**: the maximum space an app's images can take up in the registry, set by a platform administrator. When it's reached, Wakastart refuses to start a new build. Nothing is limited in the registry itself. See [Registry quota](26-builds#registry-quota). - **Purge**: the automatic, nightly deletion of the images of the oldest builds. Disabled by default, enabled app by app. Deployed images, and images still in use, are always kept. See [Image retention](26-builds#image-retention-automatic-purge). ## Storage - **S3 Bucket**: a container for files (objects) accessible over HTTP, identified by a unique name. No real folder hierarchy, just keys. - **Relational DB** (PostgreSQL, MySQL): tables, columns, joins, ACID transactions. For transactional data. - **NoSQL document DB** (MongoDB): collections of JSON documents, flexible schema. For evolving nested objects. - **Key-value store** (Valkey/Redis): `SET key value` / `GET key`. For caching, sessions, in-memory counters. ## Security - **Secret manager**: an encrypted vault that stores sensitive credentials (DB passwords, API keys, certificates). Wakastart provides one, isolated per app. You never access it directly: the platform injects secrets into your pods at startup. ## Network - **Gateway**: the platform's entry point for incoming HTTP traffic. It terminates TLS (certificates) and applies HttpRoute routing rules. - **HttpRoute**: a routing rule that says "this path → this service". - **DNS**: system that translates names (`api.exemple.com`) into IPs. Wakastart provisions CNAME records with the platform domain's registrar. ## CI/CD - **CI** (Continuous Integration): automated tests on every commit. Not managed by Wakastart (you use GitHub Actions, Jenkins, etc.). - **CD** (Continuous Deployment): automatic deployment after a successful build. Managed by Wakastart via auto-deploy. 5:["$","$L10",null,{"locale":"en","versions":[{"id":"v1.0","label":"1.0","date":"2026-05-19","status":"stable"}],"sections":[{"id":"user","label":"Utilisateur","icon":"BookOpen"},{"id":"dev","label":"Développeur","icon":"Code2"}],"latestVersion":"v1.0","currentVersion":"v1.0","searchEntries":[{"id":"v1.0-user-01-getting-started-0","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"01-getting-started","chapterTitle":"Login and authentication","heading":"When do you use this section?","snippet":"- You are logging in to WakaStart for the first time\n- You want to switch organization or account\n- You forgot your password","anchor":"when-do-you-use-this-section"},{"id":"v1.0-user-01-getting-started-1","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"01-getting-started","chapterTitle":"Login and authentication","heading":"Logging in to WakaStart","snippet":"","anchor":"logging-in-to-wakastart"},{"id":"v1.0-user-01-getting-started-2","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"01-getting-started","chapterTitle":"Login and authentication","heading":"Step 1 — Enter your business email address","snippet":"On the home page, enter the email address you were invited with. Click **Continue**.\n\nIf your address is not recognized, you will see the message: \"No account found for this email.\" Check what you ent","anchor":"step-1-enter-your-business-email-address"},{"id":"v1.0-user-01-getting-started-3","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"01-getting-started","chapterTitle":"Login and authentication","heading":"Step 2 — Choose your organization (if you have several)","snippet":"If your email address is linked to several organizations, a list is displayed. Click the organization you want to work in.","anchor":"step-2-choose-your-organization-if-you-have-several"},{"id":"v1.0-user-01-getting-started-4","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"01-getting-started","chapterTitle":"Login and authentication","heading":"Step 3 — Enter your password","snippet":"You are redirected to your organization's login page. Enter your password and confirm. You then land directly on your dashboard.","anchor":"step-3-enter-your-password"},{"id":"v1.0-user-01-getting-started-5","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"01-getting-started","chapterTitle":"Login and authentication","heading":"First access","snippet":"The very first time you log in, a welcome message is displayed to guide you through discovering the platform. You can close it at any time by clicking **Dismiss**.","anchor":"first-access"},{"id":"v1.0-user-01-getting-started-6","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"01-getting-started","chapterTitle":"Login and authentication","heading":"Practical options","snippet":"- **Switch between light and dark theme**: use the button at the top right of the login page according to your display preferences.","anchor":"practical-options"},{"id":"v1.0-user-01-getting-started-7","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"01-getting-started","chapterTitle":"Login and authentication","heading":"Learn more","snippet":"- [Discover the dashboard](./dashboard)\n- [Edit your personal information](./profile)","anchor":"learn-more"},{"id":"v1.0-user-02-dashboard-0","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"02-dashboard","chapterTitle":"Main dashboard","heading":"What you see on the dashboard","snippet":"","anchor":"what-you-see-on-the-dashboard"},{"id":"v1.0-user-02-dashboard-1","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"02-dashboard","chapterTitle":"Main dashboard","heading":"Key counters","snippet":"At the top of the page, several counters display the important figures of your platform at a glance: number of active **Partners**, **Networks**, **Customers**, **Users**, and **Applications**.\n\nThese","anchor":"key-counters"},{"id":"v1.0-user-02-dashboard-2","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"02-dashboard","chapterTitle":"Main dashboard","heading":"Recent activity feed","snippet":"Below the counters, you find the last 5 important actions (creation, modification of customers or users). A **Refresh** button lets you update the list on demand.","anchor":"recent-activity-feed"},{"id":"v1.0-user-02-dashboard-3","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"02-dashboard","chapterTitle":"Main dashboard","heading":"The dashboard header","snippet":"The bar at the top of the screen is always visible and gives you access to the essential functions:\n\n- **Your first name**: personalized welcome message\n- **Your credit balance**: updated automaticall","anchor":"the-dashboard-header"},{"id":"v1.0-user-02-dashboard-4","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"02-dashboard","chapterTitle":"Main dashboard","heading":"The global filter","snippet":"A contextual navigation bar appears at the top of every page. It lets you restrict the display to a specific **Partner**, **Network**, and/or **Customer**.\n\nMost lists on the platform automatically ad","anchor":"the-global-filter"},{"id":"v1.0-user-02-dashboard-5","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"02-dashboard","chapterTitle":"Main dashboard","heading":"Learn more","snippet":"- [Manage your partners](./partners)\n- [Manage your customers](./customers)\n- [Edit your personal preferences](./profile)","anchor":"learn-more"},{"id":"v1.0-user-03-partners-0","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"03-partners","chapterTitle":"Partners","heading":"When do you use this section?","snippet":"- You want to **register a new partner company** on the platform\n- You want to **view or edit the information** of an existing partner\n- You need to **track the consulting hours balance** associated w","anchor":"when-do-you-use-this-section"},{"id":"v1.0-user-03-partners-1","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"03-partners","chapterTitle":"Partners","heading":"Accessing the partner list","snippet":"From the main menu on the left, click **Organization** then **Partners**.\n\nThe list displays, for each partner: its **name**, the associated **legal entity**, its **status** (Active, Inactive, Suspend","anchor":"accessing-the-partner-list"},{"id":"v1.0-user-03-partners-2","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"03-partners","chapterTitle":"Partners","heading":"Creating a partner","snippet":"1. Click **+ New partner** at the top right.\n2. Fill in the requested information:\n - **Name**: the partner's commercial name (required, 100 characters max)\n - **Description**: short presentation ","anchor":"creating-a-partner"},{"id":"v1.0-user-03-partners-3","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"03-partners","chapterTitle":"Partners","heading":"Editing a partner","snippet":"Click the pencil icon next to the desired partner. The form is identical to the creation one, except for the legal entity, which can no longer be changed after initial creation.","anchor":"editing-a-partner"},{"id":"v1.0-user-03-partners-4","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"03-partners","chapterTitle":"Partners","heading":"Deleting a partner","snippet":"Click the trash icon, then confirm. Deletion is permanent.","anchor":"deleting-a-partner"},{"id":"v1.0-user-03-partners-5","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"03-partners","chapterTitle":"Partners","heading":"Viewing a partner's detail page","snippet":"Click the partner's **name** in the list to access its full record. There you find the applications and networks attached to it.","anchor":"viewing-a-partners-detail-page"},{"id":"v1.0-user-03-partners-6","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"03-partners","chapterTitle":"Partners","heading":"Learn more","snippet":"- [Manage a partner's networks](./networks)\n- [Manage legal entities](./entities)","anchor":"learn-more"},{"id":"v1.0-user-04-networks-0","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"04-networks","chapterTitle":"Networks","heading":"When do you use this section?","snippet":"- You want to **create a new network** to group customers\n- You want to **configure the settings** of an existing network (language, theme, subdomain)\n- You need to **view the customers** attached to ","anchor":"when-do-you-use-this-section"},{"id":"v1.0-user-04-networks-1","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"04-networks","chapterTitle":"Networks","heading":"Accessing the network list","snippet":"From the main menu on the left, click **Organization** then **Networks**.\n\nThe list displays, for each network: its **name**, the owning **application**, its **status**, and its **short subdomain**. Y","anchor":"accessing-the-network-list"},{"id":"v1.0-user-04-networks-2","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"04-networks","chapterTitle":"Networks","heading":"Creating a network","snippet":"1. Click **+ New network** at the top right.\n2. Fill in the requested information:\n - **Name**: the network's name as it will appear in the interface (required)\n - **Description**: short presentat","anchor":"creating-a-network"},{"id":"v1.0-user-04-networks-3","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"04-networks","chapterTitle":"Networks","heading":"Configuring an existing network","snippet":"Click the gear icon next to the network to access its detailed configuration. There you can manage attached customers, enabled features, and advanced options.","anchor":"configuring-an-existing-network"},{"id":"v1.0-user-04-networks-4","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"04-networks","chapterTitle":"Networks","heading":"Deleting a network","snippet":"Click the trash icon, then confirm. First make sure all customers in the network are either migrated or deleted.","anchor":"deleting-a-network"},{"id":"v1.0-user-04-networks-5","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"04-networks","chapterTitle":"Networks","heading":"URL redirects","snippet":"> A URL redirect lets you point a custom subdomain to a specific page of your application — handy for giving a memorable address to a network, without exposing the app's actual technical URL.","anchor":"url-redirects"},{"id":"v1.0-user-04-networks-6","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"04-networks","chapterTitle":"Networks","heading":"When do you use this feature?","snippet":"- You want to **offer a dedicated address** for your network, redirecting to a specific page of the application (landing page, login portal, etc.)\n- You need to **change the target environment or page","anchor":"when-do-you-use-this-feature"},{"id":"v1.0-user-04-networks-7","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"04-networks","chapterTitle":"Networks","heading":"Creating a redirect","snippet":"1. From the network's detailed configuration, open the **URL Redirects** tab.\n2. Click **+ New redirect**.\n3. Fill in the **Source block**:\n - **Domain**: a custom domain of the application, or the ","anchor":"creating-a-redirect"},{"id":"v1.0-user-04-networks-8","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"04-networks","chapterTitle":"Networks","heading":"Editing the destination","snippet":"You can change the targeted **route**, **environment**, **path**, or **query parameters** at any time, without recreating the redirect or affecting the source address already communicated to your cust","anchor":"editing-the-destination"},{"id":"v1.0-user-04-networks-9","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"04-networks","chapterTitle":"Networks","heading":"Tracking a redirect's status","snippet":"| Displayed status | Meaning |\n|-----------------|----------------|\n| **Pending** | The redirect has just been created, awaiting processing |\n| **Being created** | Technical resources are being provis","anchor":"tracking-a-redirects-status"},{"id":"v1.0-user-04-networks-10","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"04-networks","chapterTitle":"Networks","heading":"Deleting a redirect","snippet":"Click the trash icon next to the redirect, then confirm. Deletion never affects the route or environment targeted by the destination.","anchor":"deleting-a-redirect"},{"id":"v1.0-user-04-networks-11","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"04-networks","chapterTitle":"Networks","heading":"Learn more","snippet":"- [Manage a network's customers](./customers)\n- [Enable features for a network](./settings)\n- [Understand the technical mechanism of URL redirects](../dev/url-redirects)","anchor":"learn-more"},{"id":"v1.0-user-05-customers-0","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"05-customers","chapterTitle":"Customers","heading":"When do you use this section?","snippet":"- You want to **add a new customer organization** to your network\n- You want to **edit the information** of an existing customer\n- You need to **suspend or delete** a customer\n- You want to **view the","anchor":"when-do-you-use-this-section"},{"id":"v1.0-user-05-customers-1","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"05-customers","chapterTitle":"Customers","heading":"Accessing the customer list","snippet":"From the main menu on the left, click **Organization** then **Customers**.\n\nThe list displays, for each customer: its **name**, the **network** it belongs to, the associated **application**, its **sta","anchor":"accessing-the-customer-list"},{"id":"v1.0-user-05-customers-2","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"05-customers","chapterTitle":"Customers","heading":"Creating a customer","snippet":"> Before creating a customer, make sure you have selected a network in the global filter at the top of the page. Without this selection, creation is blocked.\n\n1. Click **+ New customer** at the top ri","anchor":"creating-a-customer"},{"id":"v1.0-user-05-customers-3","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"05-customers","chapterTitle":"Customers","heading":"Configuring an existing customer","snippet":"Click the gear icon next to the customer to access its full configuration page: theme, domains, enabled features, and advanced options.","anchor":"configuring-an-existing-customer"},{"id":"v1.0-user-05-customers-4","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"05-customers","chapterTitle":"Customers","heading":"Deleting a customer","snippet":"Click the trash icon. If the customer has associated data (users, teams, profiles, etc.), a summary is shown to you. To confirm deletion, you will need to enter the customer's **unique code**. This op","anchor":"deleting-a-customer"},{"id":"v1.0-user-05-customers-5","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"05-customers","chapterTitle":"Customers","heading":"URL redirects","snippet":"> A URL redirect lets you point a custom subdomain to a specific page of your application — handy for giving a memorable address to a customer, without exposing the app's actual technical URL.","anchor":"url-redirects"},{"id":"v1.0-user-05-customers-6","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"05-customers","chapterTitle":"Customers","heading":"When do you use this feature?","snippet":"- You want to **offer a dedicated address** for this customer, redirecting to a specific page of the application (login portal, personalized space, etc.)\n- You need to **change the target environment ","anchor":"when-do-you-use-this-feature"},{"id":"v1.0-user-05-customers-7","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"05-customers","chapterTitle":"Customers","heading":"Creating a redirect","snippet":"1. From the customer's configuration page, open the **URL Redirects** tab.\n2. Click **+ New redirect**.\n3. Fill in the **Source block**:\n - **Domain**: a custom domain of the application, or the pla","anchor":"creating-a-redirect"},{"id":"v1.0-user-05-customers-8","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"05-customers","chapterTitle":"Customers","heading":"Editing the destination","snippet":"You can change the targeted **route**, **environment**, **path**, or **query parameters** at any time, without recreating the redirect or affecting the source address already communicated to this cust","anchor":"editing-the-destination"},{"id":"v1.0-user-05-customers-9","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"05-customers","chapterTitle":"Customers","heading":"Tracking a redirect's status","snippet":"| Displayed status | Meaning |\n|-----------------|----------------|\n| **Pending** | The redirect has just been created, awaiting processing |\n| **Being created** | Technical resources are being provis","anchor":"tracking-a-redirects-status"},{"id":"v1.0-user-05-customers-10","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"05-customers","chapterTitle":"Customers","heading":"Deleting a redirect","snippet":"Click the trash icon next to the redirect, then confirm. Deletion never affects the route or environment targeted by the destination.","anchor":"deleting-a-redirect"},{"id":"v1.0-user-05-customers-11","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"05-customers","chapterTitle":"Customers","heading":"Learn more","snippet":"- [Manage a customer's users](./users)\n- [Organize users into teams](./teams)\n- [Enable features for a customer](./settings)\n- [Understand the technical mechanism of URL redirects](../dev/url-redirect","anchor":"learn-more"},{"id":"v1.0-user-06-users-0","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"06-users","chapterTitle":"Users","heading":"When do you use this section?","snippet":"- You want to **invite a new administrator** to the platform\n- You need to **change the access level** of an existing user\n- You want to **activate or deactivate** a user account\n- You need to **assig","anchor":"when-do-you-use-this-section"},{"id":"v1.0-user-06-users-1","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"06-users","chapterTitle":"Users","heading":"Accessing the user list","snippet":"From the main menu on the left, click **Organization** then **Users**.\n\nThe list displays, for each user: their **email address**, their **full name**, the **Customer** they belong to, their **adminis","anchor":"accessing-the-user-list"},{"id":"v1.0-user-06-users-2","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"06-users","chapterTitle":"Users","heading":"Creating a user","snippet":"1. Click **+ New user** at the top right.\n2. Fill in the information across the different tabs:","anchor":"creating-a-user"},{"id":"v1.0-user-06-users-3","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"06-users","chapterTitle":"Users","heading":"General tab","snippet":"- **Customer**: the Customer this user belongs to\n- **Email address**: the address that will serve as login identifier\n- **First name** and **Last name**\n- **Temporary password**: optional — if provid","anchor":"general-tab"},{"id":"v1.0-user-06-users-4","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"06-users","chapterTitle":"Users","heading":"Permissions tab","snippet":"- **Administration level**: defines what the user can manage on the platform. You cannot assign a level higher than your own.\n- **User level**: access level within the client application","anchor":"permissions-tab"},{"id":"v1.0-user-06-users-5","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"06-users","chapterTitle":"Users","heading":"HDS tab (health data)","snippet":"If your platform is HDS-certified, you can assign specific roles to this user to control their access to health data:\n\n- **HDS Administrator** — global management of health data\n- **Patient** — access","anchor":"hds-tab-health-data"},{"id":"v1.0-user-06-users-6","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"06-users","chapterTitle":"Users","heading":"Profiles tab","snippet":"Select the application profiles to assign to this user (profiles define their rights within the applications).\n\n3. Click **Create**.","anchor":"profiles-tab"},{"id":"v1.0-user-06-users-7","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"06-users","chapterTitle":"Users","heading":"Managing a Customer's users","snippet":"By accessing a customer's record, you can directly manage its users' accounts via the **Users** tab. You can:\n\n- **Deactivate** or **reactivate** an account\n- **Reset the password**: a reset email is ","anchor":"managing-a-customers-users"},{"id":"v1.0-user-06-users-8","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"06-users","chapterTitle":"Users","heading":"Learn more","snippet":"- [Create and manage application profiles](./profiles-rights)\n- [Organize users into teams](./teams)\n- [Manage HDS roles](./hds)","anchor":"learn-more"},{"id":"v1.0-user-07-teams-0","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"07-teams","chapterTitle":"Teams","heading":"When do you use this section?","snippet":"- You want to **create a working group** within a Customer\n- You want to **assign users** to an existing team\n- You need to **define different access levels** for subgroups (e.g., a team of managers w","anchor":"when-do-you-use-this-section"},{"id":"v1.0-user-07-teams-1","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"07-teams","chapterTitle":"Teams","heading":"Accessing the team list","snippet":"From the main menu on the left, click **Organization** then **Teams**.\n\nThe list displays, for each team: its **name**, its **description**, the **customer** it belongs to, and the **number of members","anchor":"accessing-the-team-list"},{"id":"v1.0-user-07-teams-2","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"07-teams","chapterTitle":"Teams","heading":"Creating a team","snippet":"1. Click **+ New team** at the top right.\n2. Fill in the team's **name** and a short **description**.\n3. Click **Create**.","anchor":"creating-a-team"},{"id":"v1.0-user-07-teams-3","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"07-teams","chapterTitle":"Teams","heading":"Managing a team's members","snippet":"1. Click the **Manage members** icon (people) next to the team.\n2. The list of all the customer's users is displayed.\n3. For each user, you can:\n - **Check the box** to add them to the team (or unch","anchor":"managing-a-teams-members"},{"id":"v1.0-user-07-teams-4","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"07-teams","chapterTitle":"Teams","heading":"Editing or deleting a team","snippet":"- Click the **pencil** icon to edit the team's name or description.\n- Click the **trash** icon to delete the team. Member users are not deleted, only unlinked from the team.","anchor":"editing-or-deleting-a-team"},{"id":"v1.0-user-07-teams-5","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"07-teams","chapterTitle":"Teams","heading":"Learn more","snippet":"- [Manage a customer's users](./users)\n- [Create application profiles](./profiles-rights)","anchor":"learn-more"},{"id":"v1.0-user-08-applications-0","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"08-applications","chapterTitle":"Applications","heading":"When do you use this section?","snippet":"- You want to **register a new application** on the platform\n- You want to **check the deployment status** of an application\n- You need to **configure the settings** of an existing application\n- You w","anchor":"when-do-you-use-this-section"},{"id":"v1.0-user-08-applications-1","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"08-applications","chapterTitle":"Applications","heading":"Accessing the application list","snippet":"From the main menu on the left, click **Applications**.\n\nThe list shows, for each application: its **name**, its **type** (Application, Module, or Service), the **owning partner**, and its **deploymen","anchor":"accessing-the-application-list"},{"id":"v1.0-user-08-applications-2","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"08-applications","chapterTitle":"Applications","heading":"Creating an application","snippet":"1. Click **+ New application** at the top right.\n2. Fill in the information:\n - **Owning partner**: the partner to whom this application belongs\n - **Name**: the application's name (required)\n -","anchor":"creating-an-application"},{"id":"v1.0-user-08-applications-3","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"08-applications","chapterTitle":"Applications","heading":"Deleting an application","snippet":"Click the trash icon. To confirm, you'll need to enter the application's **exact name**. This operation is irreversible.","anchor":"deleting-an-application"},{"id":"v1.0-user-08-applications-4","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"08-applications","chapterTitle":"Applications","heading":"Managing legal documents","snippet":"When an application is marked as commercial, you can write and manage its legal documents (terms of use, privacy policy, etc.) through the built-in document editor.\n\nThe editor offers rich formatting ","anchor":"managing-legal-documents"},{"id":"v1.0-user-08-applications-5","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"08-applications","chapterTitle":"Applications","heading":"Managing an application's infrastructure","snippet":"Click the **rocket** icon next to an application to access its infrastructure view. There you'll find:\n\n- **Architecture**: the associated services, repositories, dependencies, and addresses\n- **Build","anchor":"managing-an-applications-infrastructure"},{"id":"v1.0-user-08-applications-6","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"08-applications","chapterTitle":"Applications","heading":"Viewing URLs by environment","snippet":"Click the **View URLs** icon (external link) next to an application to open the **URLs by environment** window. It lists, for each environment (dev, staging, prod): its name, its type, and the applica","anchor":"viewing-urls-by-environment"},{"id":"v1.0-user-08-applications-7","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"08-applications","chapterTitle":"Applications","heading":"Going further","snippet":"- [Create profiles and rights for an application](./profiles-rights)\n- [Manage programmatic access keys](./api-keys)\n- [View an application's audit logs](./audit-logs)","anchor":"going-further"},{"id":"v1.0-user-09-profiles-rights-0","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"09-profiles-rights","chapterTitle":"Profiles and rights","heading":"When do you use this section?","snippet":"- You want to **create a new profile** for a group of users with the same access needs\n- You want to **modify the rights** of an existing profile\n- You need to **assign a profile** to a user","anchor":"when-do-you-use-this-section"},{"id":"v1.0-user-09-profiles-rights-1","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"09-profiles-rights","chapterTitle":"Profiles and rights","heading":"Accessing the profile list","snippet":"From the main menu on the left, click **Applications** then **Profiles**.\n\nThe list shows, for each profile: its **name**, its **description**, and the **application** it belongs to. Profiles marked *","anchor":"accessing-the-profile-list"},{"id":"v1.0-user-09-profiles-rights-2","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"09-profiles-rights","chapterTitle":"Profiles and rights","heading":"Creating a profile","snippet":"1. Click **+ New profile** at the top right.\n2. **General** tab: enter the profile's **name**, a **description**, and select the relevant **application** (locked once editing).\n3. Still in the General","anchor":"creating-a-profile"},{"id":"v1.0-user-09-profiles-rights-3","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"09-profiles-rights","chapterTitle":"Profiles and rights","heading":"Available rights","snippet":"The AppRights tab displays a list of checkboxes specific to the selected application — it is not fixed: some rights correspond to broad legacy categories, others are fine-grained rights defined applic","anchor":"available-rights"},{"id":"v1.0-user-09-profiles-rights-4","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"09-profiles-rights","chapterTitle":"Profiles and rights","heading":"Modifying or deleting a profile","snippet":"- Click the **pencil** icon to edit an existing profile.\n- Click the **trash** icon to delete it. Users with this profile will lose the associated rights.\n\n> Profiles marked **System** cannot be modif","anchor":"modifying-or-deleting-a-profile"},{"id":"v1.0-user-09-profiles-rights-5","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"09-profiles-rights","chapterTitle":"Profiles and rights","heading":"Assigning a profile to a user","snippet":"Assignment is done from the user's record, **Profiles** tab. You can add or remove profiles at any time; the effect is immediate.","anchor":"assigning-a-profile-to-a-user"},{"id":"v1.0-user-09-profiles-rights-6","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"09-profiles-rights","chapterTitle":"Profiles and rights","heading":"Going further","snippet":"- [Manage users](./users)\n- [Manage programmatic access keys](./api-keys)","anchor":"going-further"},{"id":"v1.0-user-10-api-keys-0","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"10-api-keys","chapterTitle":"API Keys","heading":"When do you use this section?","snippet":"- You want to **connect an external tool** to WakaStart (deployment tool, monitoring software, automation script)\n- You need to **create a technical account with limited rights** for a specific integr","anchor":"when-do-you-use-this-section"},{"id":"v1.0-user-10-api-keys-1","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"10-api-keys","chapterTitle":"API Keys","heading":"Accessing the API key list","snippet":"From the main menu on the left, click **Applications** then **API Keys**. Existing keys are displayed as **cards** (not a table): each card shows the name and its status, the masked key (prefix follow","anchor":"accessing-the-api-key-list"},{"id":"v1.0-user-10-api-keys-2","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"10-api-keys","chapterTitle":"API Keys","heading":"Creating an API key (technical account)","snippet":"1. Click **+ New key** at the top right. The window specifies that this is an autonomous principal, independent of any user.\n2. Fill in the required information, in order:\n - **Customer (tenant)**: ","anchor":"creating-an-api-key-technical-account"},{"id":"v1.0-user-10-api-keys-3","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"10-api-keys","chapterTitle":"API Keys","heading":"Revoking an API key","snippet":"Click the trash icon next to the key. Revocation is immediate and irreversible.","anchor":"revoking-an-api-key"},{"id":"v1.0-user-10-api-keys-4","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"10-api-keys","chapterTitle":"API Keys","heading":"Going further","snippet":"- [Manage profiles and rights](./profiles-rights)\n- [View audit logs](./audit-logs)","anchor":"going-further"},{"id":"v1.0-user-27-tickets-0","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"27-tickets","chapterTitle":"Ticket management","heading":"Creating a ticket","snippet":"From an App's ticket list, open the creation form. A ticket includes:\n\n- **Title** and **description** (rich text editor, you can paste images directly into the description).\n- **Type**: `Bug`, `Featu","anchor":"creating-a-ticket"},{"id":"v1.0-user-27-tickets-1","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"27-tickets","chapterTitle":"Ticket management","heading":"Statuses","snippet":"A ticket follows one of 9 possible statuses:\n\n| Status | Meaning |\n|--------|----------------|\n| Later | Reported but not yet scheduled |\n| Open | New ticket, not yet picked up |\n| In progress | Curre","anchor":"statuses"},{"id":"v1.0-user-27-tickets-2","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"27-tickets","chapterTitle":"Ticket management","heading":"Assignment","snippet":"A ticket can be assigned to an administrator authorized on the App concerned. The list of eligible assignees is computed dynamically based on rights on the application.","anchor":"assignment"},{"id":"v1.0-user-27-tickets-3","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"27-tickets","chapterTitle":"Ticket management","heading":"Visibility: Waka or Client","snippet":"Every ticket carries a visibility setting:\n\n- **Waka**: visible only to Wakastellar teams.\n- **Client**: also visible to the concerned client (Customer).\n\nThis visibility can be changed after creation","anchor":"visibility-waka-or-client"},{"id":"v1.0-user-27-tickets-4","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"27-tickets","chapterTitle":"Ticket management","heading":"Comments","snippet":"Each ticket has a comment thread: creating, editing, and deleting a comment are all possible (deletion is logical, never physical — the comment stays tracked platform-side).","anchor":"comments"},{"id":"v1.0-user-27-tickets-5","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"27-tickets","chapterTitle":"Ticket management","heading":"Attachments","snippet":"You can attach files to a ticket (up to 20 attachments per ticket). Each attachment follows this cycle:\n\n1. Upload request (presigned S3 URL).\n2. File upload, then confirmation.\n3. Automatic backgroun","anchor":"attachments"},{"id":"v1.0-user-27-tickets-6","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"27-tickets","chapterTitle":"Ticket management","heading":"History","snippet":"Every ticket keeps a history of changes (status, assignment, priority, etc.), with the people involved shown by name rather than by technical identifier.","anchor":"history"},{"id":"v1.0-user-27-tickets-7","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"27-tickets","chapterTitle":"Ticket management","heading":"Deletion","snippet":"Deleting a ticket is restricted to its author, and remains a logical deletion (the ticket is hidden, not destroyed).","anchor":"deletion"},{"id":"v1.0-user-27-tickets-8","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"27-tickets","chapterTitle":"Ticket management","heading":"Going further","snippet":"- [Applications](08-applications): manage your applications and their rights\n- [Access control](../dev/07-access-control-model): understand admin levels","anchor":"going-further"},{"id":"v1.0-user-11-audit-logs-0","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"11-audit-logs","chapterTitle":"Audit Logs","heading":"When do you use this section?","snippet":"- You need to **verify that an action was actually performed** (e.g., was a user really deactivated?)\n- You want to **detect suspicious behavior** (failed login attempts, unusual access)\n- You are pre","anchor":"when-do-you-use-this-section"},{"id":"v1.0-user-11-audit-logs-1","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"11-audit-logs","chapterTitle":"Audit Logs","heading":"Accessing the logs","snippet":"From the main menu on the left, click **Security** then **Audit Logs**.\n\nAt the top of the page, four indicators alert you in real time:\n\n- **Total entries**: overall log volume\n- **Critical (24h)**: ","anchor":"accessing-the-logs"},{"id":"v1.0-user-11-audit-logs-2","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"11-audit-logs","chapterTitle":"Audit Logs","heading":"Filtering the logs","snippet":"Use the filters at the top of the list to refine your search:\n\n- **User ID**: to see all actions by a specific person\n- **Severity level**: Critical, Error, Alert, Warning, Information\n- **Action type","anchor":"filtering-the-logs"},{"id":"v1.0-user-11-audit-logs-3","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"11-audit-logs","chapterTitle":"Audit Logs","heading":"Verifying log integrity","snippet":"You can select several log entries and click **Verify** to check that these entries have not been tampered with. A green icon confirms integrity, a red icon indicates an anomaly to investigate.","anchor":"verifying-log-integrity"},{"id":"v1.0-user-11-audit-logs-4","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"11-audit-logs","chapterTitle":"Audit Logs","heading":"Exporting the logs","snippet":"1. Click **Export** (or press **E**).\n2. Choose the format: structured table or delimited file.\n3. Define the desired date range.\n4. Enter the **export reason** (required for every export).\n5. Confirm","anchor":"exporting-the-logs"},{"id":"v1.0-user-11-audit-logs-5","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"11-audit-logs","chapterTitle":"Audit Logs","heading":"Keyboard shortcuts","snippet":"| Key | Action |\n|--------|--------|\n| **R** | Refresh the list |\n| **F** | Open filters |\n| **E** | Export |\n| **Esc** | Close the window |\n| **J / K** | Navigate between entries |","anchor":"keyboard-shortcuts"},{"id":"v1.0-user-11-audit-logs-6","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"11-audit-logs","chapterTitle":"Audit Logs","heading":"Going further","snippet":"- [HDS Module — compliance and regulatory reports](./hds)\n- [Stellar Module — blockchain integrity proofs](./stellar)","anchor":"going-further"},{"id":"v1.0-user-15-antivirus-0","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"15-antivirus","chapterTitle":"Antivirus Module","heading":"When do you use this section?","snippet":"- You want to **check that the antivirus service is operational**\n- A file has been **placed in quarantine** and you need to decide what to do with it\n- You want to **view pending scans** or those alr","anchor":"when-do-you-use-this-section"},{"id":"v1.0-user-15-antivirus-1","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"15-antivirus","chapterTitle":"Antivirus Module","heading":"Antivirus dashboard","snippet":"From the main menu on the left, click **Security** then **Antivirus**.\n\nThe main indicators are displayed:\n\n- **Service status**: Operational, Degraded, or Offline — a colored indicator alerts you imm","anchor":"antivirus-dashboard"},{"id":"v1.0-user-15-antivirus-2","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"15-antivirus","chapterTitle":"Antivirus Module","heading":"Managing quarantine","snippet":"Go to the **Quarantine** section to view files placed on hold. For each file, you can:\n- **Release** the file if you identify it as safe (false positive)\n- **Permanently delete** the file if it is con","anchor":"managing-quarantine"},{"id":"v1.0-user-15-antivirus-3","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"15-antivirus","chapterTitle":"Antivirus Module","heading":"Tracking the scan queue","snippet":"The **Queue** section lists files being scanned or awaiting processing. You can monitor the progress of operations and identify any bottlenecks.","anchor":"tracking-the-scan-queue"},{"id":"v1.0-user-15-antivirus-4","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"15-antivirus","chapterTitle":"Antivirus Module","heading":"Configuring scan policies","snippet":"The **Policies** section lets you define scan rules: which file types to scan, which action to apply automatically when something is detected (quarantine, block, notification...).","anchor":"configuring-scan-policies"},{"id":"v1.0-user-15-antivirus-5","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"15-antivirus","chapterTitle":"Antivirus Module","heading":"Going further","snippet":"- [Audit Logs — tracing security events](./audit-logs)\n- [HDS Module — health data security](./hds)","anchor":"going-further"},{"id":"v1.0-user-20-hds-0","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"20-hds","chapterTitle":"HDS Module","heading":"When do you use this section?","snippet":"- You want to **monitor activity** on health data (logins, vault access, modifications)\n- You need to **verify the integrity** of data stored in vaults\n- You want to **view emergency access** (excepti","anchor":"when-do-you-use-this-section"},{"id":"v1.0-user-20-hds-1","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"20-hds","chapterTitle":"HDS Module","heading":"Overview","snippet":"From the main menu, click **Security** then **HDS**.\n\nThe indicators display in real time:\n\n- **Active networks**: the number of operational HDS networks\n- **Data vaults**: the number of vaults (secur","anchor":"overview"},{"id":"v1.0-user-20-hds-2","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"20-hds","chapterTitle":"HDS Module","heading":"Viewing transactions","snippet":"The **Transactions** section lists all events tracked on health data, classified by category: authentication, vault access, document handling, permission changes, consents, emergency access, administr","anchor":"viewing-transactions"},{"id":"v1.0-user-20-hds-3","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"20-hds","chapterTitle":"HDS Module","heading":"Verifying data integrity","snippet":"1. Go to **HDS** then **Integrity**.\n2. Select the network to audit from the dropdown menu.\n3. Click **Verify integrity**.\n4. The result is displayed with a **Valid** (green) or **Invalid** (red) badg","anchor":"verifying-data-integrity"},{"id":"v1.0-user-20-hds-4","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"20-hds","chapterTitle":"HDS Module","heading":"Security — Access and incidents","snippet":"The **Security** section displays three counters:\n\n- **Emergency access**: number of uses of \"break glass\" mode (exceptional access to normally restricted data)\n- **Authentication failures**: failed l","anchor":"security-access-and-incidents"},{"id":"v1.0-user-20-hds-5","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"20-hds","chapterTitle":"HDS Module","heading":"Managing HDS permissions","snippet":"The **Permissions** section gives you an overview of the rights granted to each user across the various HDS networks. You can quickly identify who has access to what and adjust as needed.","anchor":"managing-hds-permissions"},{"id":"v1.0-user-20-hds-6","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"20-hds","chapterTitle":"HDS Module","heading":"Generating regulatory reports","snippet":"1. Go to **HDS** then **Compliance**.\n2. Choose the report type: **HDS Audit**, **GDPR**, or **NIS2**.\n3. Click **Generate**.\n\nGeneration may take a few moments. The status goes from **Pending** to **","anchor":"generating-regulatory-reports"},{"id":"v1.0-user-20-hds-7","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"20-hds","chapterTitle":"HDS Module","heading":"HDS backups","snippet":"The **Backups** section lets you trigger or view backups of health data. A single backup mechanism is available: a database dump followed by secure storage on S3.","anchor":"hds-backups"},{"id":"v1.0-user-20-hds-8","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"20-hds","chapterTitle":"HDS Module","heading":"Going further","snippet":"- [Audit Logs](./audit-logs)\n- [Stellar Module — blockchain integrity proofs](./stellar)\n- [Manage users' HDS roles](./users)","anchor":"going-further"},{"id":"v1.0-user-16-stellar-0","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"16-stellar","chapterTitle":"Stellar Module (blockchain proofs)","heading":"When do you use this section?","snippet":"- You need to **prove to an external auditor** that your logs have not been tampered with\n- You want to **verify that synchronizations** with the blockchain are proceeding normally\n- You want to **vie","anchor":"when-do-you-use-this-section"},{"id":"v1.0-user-16-stellar-1","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"16-stellar","chapterTitle":"Stellar Module (blockchain proofs)","heading":"Accessing blockchain proofs","snippet":"From the main menu on the left, click **Security** then **Stellar**.\n\nThe indicators at the top of the page give you a quick overview:\n\n- **Number of recorded proofs**: the total number of fingerprint","anchor":"accessing-blockchain-proofs"},{"id":"v1.0-user-16-stellar-2","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"16-stellar","chapterTitle":"Stellar Module (blockchain proofs)","heading":"Viewing proof details","snippet":"The table lists all recorded proofs. You can filter by **network**, by **status** (success, error, pending), and by **period**.\n\nEach row shows the anchoring date, the relevant network, and a blockcha","anchor":"viewing-proof-details"},{"id":"v1.0-user-16-stellar-3","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"16-stellar","chapterTitle":"Stellar Module (blockchain proofs)","heading":"Going further","snippet":"- [View audit logs](./audit-logs)\n- [HDS Module — compliance and regulatory reports](./hds)","anchor":"going-further"},{"id":"v1.0-user-12-credits-0","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"12-credits","chapterTitle":"Credits","heading":"When do you use this section?","snippet":"- You want to **check your available balance**\n- You want to **identify the most consumption-heavy operations**\n- You need to **justify consumption** as part of budget tracking","anchor":"when-do-you-use-this-section"},{"id":"v1.0-user-12-credits-1","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"12-credits","chapterTitle":"Credits","heading":"Accessing credit tracking","snippet":"From the main menu on the left, click **Business** then **Credits**.\n\nThree key indicators are displayed at the top of the page:\n\n- **Current balance**: the number of credits still available (shown in","anchor":"accessing-credit-tracking"},{"id":"v1.0-user-12-credits-2","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"12-credits","chapterTitle":"Credits","heading":"Analyzing your consumption","snippet":"A bar chart lets you visualize the trend in your consumption over three periods: by **day**, by **week**, or by **month**. Click the tabs to change the displayed period.\n\nBelow, a second chart present","anchor":"analyzing-your-consumption"},{"id":"v1.0-user-12-credits-3","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"12-credits","chapterTitle":"Credits","heading":"Learn more","snippet":"- [Buy credits](./billing)\n- [Configure the cost of operations](./pricing)","anchor":"learn-more"},{"id":"v1.0-user-13-billing-0","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"13-billing","chapterTitle":"Billing","heading":"When do you use this section?","snippet":"- Your credit balance is low and you need to **buy more**\n- You want to **choose a pack suited** to your usage volume","anchor":"when-do-you-use-this-section"},{"id":"v1.0-user-13-billing-1","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"13-billing","chapterTitle":"Billing","heading":"Buying credits","snippet":"From the main menu on the left, click **Business** then **Billing**.\n\nFour packs are offered:\n\n| Pack | Credits included | Price | Benefit |\n|------|---------------|------|----------|\n| **Starter** | ","anchor":"buying-credits"},{"id":"v1.0-user-13-billing-2","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"13-billing","chapterTitle":"Billing","heading":"Learn more","snippet":"- [Track your credit consumption](./credits)\n- [Configure the cost of operations](./pricing)","anchor":"learn-more"},{"id":"v1.0-user-17-projects-0","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"17-projects","chapterTitle":"Projects","heading":"When do you use this section?","snippet":"- You want to **create a new project** and track its progress\n- You need to **build the project team** and assign roles to it\n- You want to **plan milestones** on a timeline\n- You need a centralized *","anchor":"when-do-you-use-this-section"},{"id":"v1.0-user-17-projects-1","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"17-projects","chapterTitle":"Projects","heading":"Accessing the project list","snippet":"From the main menu on the left, click **Projects**.\n\nThe list displays, for each project: its **name**, its **status** (Draft, Active, Completed, Archived, Cancelled), the owning **partner**, the **pr","anchor":"accessing-the-project-list"},{"id":"v1.0-user-17-projects-2","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"17-projects","chapterTitle":"Projects","heading":"Creating a project","snippet":"1. Click **+ New project**.\n2. Fill in the name, initial status, and general information.\n3. Click **Create**.","anchor":"creating-a-project"},{"id":"v1.0-user-17-projects-3","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"17-projects","chapterTitle":"Projects","heading":"Managing an existing project","snippet":"Click the project name to access its main view. Several sections are available:\n\n- **Edit**: modify the project's general information\n- **Team**: add members and define their roles on this project\n- *","anchor":"managing-an-existing-project"},{"id":"v1.0-user-17-projects-4","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"17-projects","chapterTitle":"Projects","heading":"Writing specifications with the AI assistant","snippet":"WakaStart includes an AI-assisted specification editor. Access it from **Projects** then **Specifications**.\n\nThe assistant helps you write, structure, and complete your specifications. You can create","anchor":"writing-specifications-with-the-ai-assistant"},{"id":"v1.0-user-17-projects-5","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"17-projects","chapterTitle":"Projects","heading":"Learn more","snippet":"- [Manage partners](./partners)\n- [View a project's audit logs](./audit-logs)","anchor":"learn-more"},{"id":"v1.0-user-21-prospects-0","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"21-prospects","chapterTitle":"Prospects and Sales Management","heading":"When do you use this section?","snippet":"- You want to **track your sales opportunities** and their progress\n- You want to **create a quote** for a new prospect\n- You need to **estimate the cost** of a WakaStart project before sending it to ","anchor":"when-do-you-use-this-section"},{"id":"v1.0-user-21-prospects-1","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"21-prospects","chapterTitle":"Prospects and Sales Management","heading":"Sales dashboard","snippet":"From the main menu on the left, click **Business** then **Prospects**.\n\nThe dashboard displays:\n\n- **Total number of quotes** and their breakdown by status: Created, Sent, Rejected, Signed\n- **Current","anchor":"sales-dashboard"},{"id":"v1.0-user-21-prospects-2","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"21-prospects","chapterTitle":"Prospects and Sales Management","heading":"Managing your sales projects","snippet":"Go to the **Sales** section to view and manage your prospect files. Each file has a status: Draft, Active, To follow up, Abandoned, Lost, or Won.","anchor":"managing-your-sales-projects"},{"id":"v1.0-user-21-prospects-3","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"21-prospects","chapterTitle":"Prospects and Sales Management","heading":"Creating a quote with the estimator","snippet":"Go to **Prospects** then **Quotes** to use the WakaStart pricing estimator. It lets you build an offer by selecting the following elements:\n\n- **Starter pack**: Simple, Standard, Complex, or Custom\n- ","anchor":"creating-a-quote-with-the-estimator"},{"id":"v1.0-user-21-prospects-4","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"21-prospects","chapterTitle":"Prospects and Sales Management","heading":"TopFlix Academy estimator","snippet":"A dedicated estimator is available for the **TopFlix Academy** offer:\n\n| Plan | Monthly price | Included |\n|---------|-------------|--------|\n| **Basic** | €100/month | 10 users, 3 categories, 500 med","anchor":"topflix-academy-estimator"},{"id":"v1.0-user-21-prospects-5","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"21-prospects","chapterTitle":"Prospects and Sales Management","heading":"Learn more","snippet":"- [Project management](./projects)\n- [Billing and credits](./billing)","anchor":"learn-more"},{"id":"v1.0-user-22-entities-0","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"22-entities","chapterTitle":"Legal Entities and Contacts","heading":"When do you use this section?","snippet":"- You need to **record the legal information** of a new organization (SIRET, RCS, address...)\n- You want to **add or edit a contact** within an organization\n- You want to **view the directory** of all","anchor":"when-do-you-use-this-section"},{"id":"v1.0-user-22-entities-1","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"22-entities","chapterTitle":"Legal Entities and Contacts","heading":"Accessing entities and contacts","snippet":"From the main menu on the left, click **Business** then **Entities**.\n\nTwo tabs are available: **Entities** and **Contacts**.","anchor":"accessing-entities-and-contacts"},{"id":"v1.0-user-22-entities-2","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"22-entities","chapterTitle":"Legal Entities and Contacts","heading":"Managing legal entities","snippet":"Each entity groups together the legal and administrative information of an organization:\n\n- **Trade name** and **Legal name**\n- **Legal form** (SAS, SARL, Association...)\n- **SIRET number** and **RCS*","anchor":"managing-legal-entities"},{"id":"v1.0-user-22-entities-3","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"22-entities","chapterTitle":"Legal Entities and Contacts","heading":"Managing contacts","snippet":"Each contact is attached to a legal entity and represents a human point of contact:\n\n- **Title**, **First name**, **Last name**\n- **Role** within the organization\n- **Business email address**\n- **Land","anchor":"managing-contacts"},{"id":"v1.0-user-22-entities-4","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"22-entities","chapterTitle":"Legal Entities and Contacts","heading":"Learn more","snippet":"- [Create a partner](./partners)\n- [Create a client](./customers)","anchor":"learn-more"},{"id":"v1.0-user-25-pricing-0","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"25-pricing","chapterTitle":"Pricing Module","heading":"When do you use this section?","snippet":"- You want to **view the cost** of each action available on the platform\n- You need to **change the rate** of an action (access restricted to high-level administrators)\n- You want to **grant a discoun","anchor":"when-do-you-use-this-section"},{"id":"v1.0-user-25-pricing-1","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"25-pricing","chapterTitle":"Pricing Module","heading":"Accessing pricing","snippet":"From the main menu on the left, click **Business** then **Pricing**.\n\nThe screen is divided into two columns:\n\n- **On the left**: the list of modules (groups of actions)\n- **On the right**: the detail","anchor":"accessing-pricing"},{"id":"v1.0-user-25-pricing-2","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"25-pricing","chapterTitle":"Pricing Module","heading":"Viewing and changing rates","snippet":"Click a module in the list on the left to display its actions and their corresponding rates in credits.\n\nFor each action, you can view:\n\n- **Standard rate**: the default cost for all networks and clie","anchor":"viewing-and-changing-rates"},{"id":"v1.0-user-25-pricing-3","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"25-pricing","chapterTitle":"Pricing Module","heading":"Learn more","snippet":"- [Track credit consumption](./credits)\n- [Buy credits](./billing)","anchor":"learn-more"},{"id":"v1.0-user-14-media-0","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"14-media","chapterTitle":"Media","heading":"When do you use this section?","snippet":"- You want to **view or administer** the platform's media files\n- You need to **configure the media management service**\n- You want to **track the status of ongoing processing** (conversion, resizing,","anchor":"when-do-you-use-this-section"},{"id":"v1.0-user-14-media-1","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"14-media","chapterTitle":"Media","heading":"Accessing media management","snippet":"From the main menu on the left, click **Media**.\n\nTwo subsections are available:","anchor":"accessing-media-management"},{"id":"v1.0-user-14-media-2","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"14-media","chapterTitle":"Media","heading":"Media service configuration","snippet":"Access the service's configuration settings: supported formats, maximum file size, automatic processing options.","anchor":"media-service-configuration"},{"id":"v1.0-user-14-media-3","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"14-media","chapterTitle":"Media","heading":"Ongoing and completed processing","snippet":"View the list of processing operations (conversion, resizing, antivirus analysis...) with their status: pending, in progress, or completed. Any errors are clearly flagged so you can take action.","anchor":"ongoing-and-completed-processing"},{"id":"v1.0-user-14-media-4","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"14-media","chapterTitle":"Media","heading":"Learn more","snippet":"- [Antivirus Module — file analysis](./antivirus)\n- [Backup and restore](./backup)","anchor":"learn-more"},{"id":"v1.0-user-18-settings-0","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"18-settings","chapterTitle":"Settings","heading":"When do you use this section?","snippet":"- You want to **change the display theme** of the interface\n- You need to **connect a cloud account** (OVH, AWS, GCP...) to the platform\n- You want to **enable or disable features** for a specific net","anchor":"when-do-you-use-this-section"},{"id":"v1.0-user-18-settings-1","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"18-settings","chapterTitle":"Settings","heading":"Appearance","snippet":"From the main menu, click **Settings**.\n\nChoose your display mode from three options:\n\n- **Light**: bright theme, ideal in daylight\n- **Dark**: reduces eye strain in low-light environments\n- **System*","anchor":"appearance"},{"id":"v1.0-user-18-settings-2","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"18-settings","chapterTitle":"Settings","heading":"Cloud accounts","snippet":"Go to **Settings** then **Cloud Providers** to connect and manage your accounts with infrastructure providers (OVH, Amazon Web Services, Google Cloud Platform, etc.). These connections are used for de","anchor":"cloud-accounts"},{"id":"v1.0-user-18-settings-3","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"18-settings","chapterTitle":"Settings","heading":"Network features","snippet":"Go to **Settings** then **Network Features** to enable or disable advanced features available at the scale of your networks.","anchor":"network-features"},{"id":"v1.0-user-18-settings-4","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"18-settings","chapterTitle":"Settings","heading":"Customer features","snippet":"Go to **Settings** then **Customer Features** to enable or disable advanced features available for customer organizations.","anchor":"customer-features"},{"id":"v1.0-user-18-settings-5","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"18-settings","chapterTitle":"Settings","heading":"Learn more","snippet":"- [My profile — personal preferences](./profile)\n- [Network management](./networks)\n- [Customer management](./customers)","anchor":"learn-more"},{"id":"v1.0-user-23-identity-providers-0","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"23-identity-providers","chapterTitle":"Identity Providers (SSO)","heading":"When do you use this section?","snippet":"- You want to **let your users log in with their corporate accounts** (Google, Microsoft, Okta...)\n- You need to **enable or disable** an existing SSO connection\n- You want to **synchronize** accounts","anchor":"when-do-you-use-this-section"},{"id":"v1.0-user-23-identity-providers-1","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"23-identity-providers","chapterTitle":"Identity Providers (SSO)","heading":"Accessing identity providers","snippet":"From the main menu on the left, click **Customization** then **Identity Providers**.\n\nThe list shows the SSO connections configured for your organization, along with their status (active / inactive) a","anchor":"accessing-identity-providers"},{"id":"v1.0-user-23-identity-providers-2","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"23-identity-providers","chapterTitle":"Identity Providers (SSO)","heading":"Configuring an SSO connection","snippet":"","anchor":"configuring-an-sso-connection"},{"id":"v1.0-user-23-identity-providers-3","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"23-identity-providers","chapterTitle":"Identity Providers (SSO)","heading":"Pre-configured providers","snippet":"For common providers, configuration is simplified. Click **+ Add a provider** and select:\n\n- **Google**: sign in via a Google Workspace account\n- **Microsoft**: sign in via a Microsoft 365 / Azure acc","anchor":"pre-configured-providers"},{"id":"v1.0-user-23-identity-providers-4","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"23-identity-providers","chapterTitle":"Identity Providers (SSO)","heading":"SAML 2.0 configuration","snippet":"For enterprise identity providers that use the SAML 2.0 standard (Okta, Ping Identity, ADFS...):\n\n1. Select the **SAML 2.0** type.\n2. Enter the information provided by your IT department:\n - **Sign-","anchor":"saml-20-configuration"},{"id":"v1.0-user-23-identity-providers-5","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"23-identity-providers","chapterTitle":"Identity Providers (SSO)","heading":"OpenID Connect configuration","snippet":"For providers compatible with OpenID Connect, select the **OpenID Connect** type and follow the guided steps.","anchor":"openid-connect-configuration"},{"id":"v1.0-user-23-identity-providers-6","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"23-identity-providers","chapterTitle":"Identity Providers (SSO)","heading":"Managing an existing connection","snippet":"For each configured provider, the following actions are available:\n\n- **Enable / Disable**: immediate control of the connection\n- **Synchronize**: forces an update from the external directory\n- **Edit","anchor":"managing-an-existing-connection"},{"id":"v1.0-user-23-identity-providers-7","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"23-identity-providers","chapterTitle":"Identity Providers (SSO)","heading":"Learn more","snippet":"- [Managing users](./users)\n- [Organization settings](./settings)","anchor":"learn-more"},{"id":"v1.0-user-24-backup-0","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"24-backup","chapterTitle":"Backup and Restore","heading":"When do you use this section?","snippet":"- You want to **create a backup copy** of an application's configuration\n- You want to **duplicate an existing application** or network to create a variant\n- You need to **restore a configuration** af","anchor":"when-do-you-use-this-section"},{"id":"v1.0-user-24-backup-1","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"24-backup","chapterTitle":"Backup and Restore","heading":"Exporting a configuration","snippet":"From the main menu on the left, click **Administration** then **Backup**.\n\nThree sections let you separately export the configurations of your **Applications**, **Networks**, and **Customers**.\n\nFor e","anchor":"exporting-a-configuration"},{"id":"v1.0-user-24-backup-2","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"24-backup","chapterTitle":"Backup and Restore","heading":"Importing a configuration","snippet":"The import process consists of four guided steps:\n\n1. **Drop the file**: drag and drop your backup file into the designated area, or click to select it.\n2. **Automatic analysis**: WakaStart detects th","anchor":"importing-a-configuration"},{"id":"v1.0-user-24-backup-3","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"24-backup","chapterTitle":"Backup and Restore","heading":"Learn more","snippet":"- [Application management](./applications)\n- [Network management](./networks)\n- [Customer management](./customers)","anchor":"learn-more"},{"id":"v1.0-user-26-wakaadmin-0","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"26-wakaadmin","chapterTitle":"Platform Administration (WakaAdmin)","heading":"When do you use this section?","snippet":"- You need to **manage the domain names** used to host applications\n- You want to **configure network entry points** (traffic routing)\n- You need to **manage the image registry** for your applications","anchor":"when-do-you-use-this-section"},{"id":"v1.0-user-26-wakaadmin-1","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"26-wakaadmin","chapterTitle":"Platform Administration (WakaAdmin)","heading":"Domains","snippet":"Manage the root domain names used to host applications on the platform. The supported DNS providers are OVH and Cloudflare. From this section, you can create, edit, or delete domains and verify their ","anchor":"domains"},{"id":"v1.0-user-26-wakaadmin-2","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"26-wakaadmin","chapterTitle":"Platform Administration (WakaAdmin)","heading":"Network Gateways","snippet":"Gateways are the entry points for web traffic to hosted applications. Manage the list of gateways and their routing configuration here.","anchor":"network-gateways"},{"id":"v1.0-user-26-wakaadmin-3","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"26-wakaadmin","chapterTitle":"Platform Administration (WakaAdmin)","heading":"Harbor Image Registry","snippet":"Harbor is the registry that stores and distributes your applications' images (comparable to a warehouse of ready-to-deploy packages). Five subsections are available:\n\n- **Instances**: the Harbor serve","anchor":"harbor-image-registry"},{"id":"v1.0-user-26-wakaadmin-4","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"26-wakaadmin","chapterTitle":"Platform Administration (WakaAdmin)","heading":"Secrets Vault (OpenBao)","snippet":"OpenBao is the platform's digital vault — it securely stores the credentials, keys, and certificates needed for services to function. Three types of vaults are managed:\n\n- **Key-value (KV)**: for simp","anchor":"secrets-vault-openbao"},{"id":"v1.0-user-26-wakaadmin-5","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"26-wakaadmin","chapterTitle":"Platform Administration (WakaAdmin)","heading":"Code Repositories","snippet":"Manage the source code repositories attached to the platform for applications deployed via WakaStart.","anchor":"code-repositories"},{"id":"v1.0-user-26-wakaadmin-6","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"26-wakaadmin","chapterTitle":"Platform Administration (WakaAdmin)","heading":"SMTP Providers","snippet":"Configure the email sending servers used for notifications, invitations, and automatic platform communications. A **Test** button lets you verify that an SMTP server responds correctly before putting ","anchor":"smtp-providers"},{"id":"v1.0-user-26-wakaadmin-7","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"26-wakaadmin","chapterTitle":"Platform Administration (WakaAdmin)","heading":"Platform Variables","snippet":"Define global configuration variables accessible to all platform components. These variables let you centralize shared settings without having to enter them manually in each service.","anchor":"platform-variables"},{"id":"v1.0-user-26-wakaadmin-8","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"26-wakaadmin","chapterTitle":"Platform Administration (WakaAdmin)","heading":"Monitoring","snippet":"Configure availability monitors for your applications and services: WakaStart regularly sends a check request (\"ping\") to the monitored address and alerts you if it stops responding.","anchor":"monitoring"},{"id":"v1.0-user-26-wakaadmin-9","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"26-wakaadmin","chapterTitle":"Platform Administration (WakaAdmin)","heading":"Observability","snippet":"Access the platform's advanced supervision tools: performance metrics, execution traces, and consolidated system logs. This view is intended for technical administrators to diagnose and resolve infras","anchor":"observability"},{"id":"v1.0-user-26-wakaadmin-10","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"26-wakaadmin","chapterTitle":"Platform Administration (WakaAdmin)","heading":"Learn more","snippet":"- [Application management](./applications)\n- [Audit logs](./audit-logs)\n- [Backup and Restore](./backup)","anchor":"learn-more"},{"id":"v1.0-user-19-profile-0","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"19-profile","chapterTitle":"My Profile","heading":"When do you use this section?","snippet":"- You want to **update your contact details** (phone, job title)\n- You want to **change your interface language** or your **time zone**\n- You want to **check what rights you have** on the platform","anchor":"when-do-you-use-this-section"},{"id":"v1.0-user-19-profile-1","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"19-profile","chapterTitle":"My Profile","heading":"Accessing your profile","snippet":"Click your **avatar** at the top right of the screen, then select **My Profile**.","anchor":"accessing-your-profile"},{"id":"v1.0-user-19-profile-2","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"19-profile","chapterTitle":"My Profile","heading":"Information you can edit","snippet":"- **First name** and **Last name**\n- **Job title**: your position title\n- **Landline phone** and **Mobile phone**\n- **Time zone**: so dates and times are displayed in your reference frame\n- **Preferre","anchor":"information-you-can-edit"},{"id":"v1.0-user-19-profile-3","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"19-profile","chapterTitle":"My Profile","heading":"Read-only information","snippet":"Some information is managed by your administrator and cannot be changed from your profile:\n\n- **Email address**: your login identifier\n- **Wakastellar ID**: your unique reference on the platform\n- **A","anchor":"read-only-information"},{"id":"v1.0-user-19-profile-4","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"19-profile","chapterTitle":"My Profile","heading":"Learn more","snippet":"- [General interface settings](./settings)","anchor":"learn-more"},{"id":"v1.0-user-99-glossary-0","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"99-glossary","chapterTitle":"Glossary","heading":"Partner","snippet":"Company or entity that distributes or operates applications via WakaStart. The Partner sits at the top of the organizational hierarchy: Partner → Network → Customer → User.","anchor":"partner"},{"id":"v1.0-user-99-glossary-1","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"99-glossary","chapterTitle":"Glossary","heading":"Network","snippet":"Grouping of Customers under the same logical organization. A Network is attached to an Application and inherits its base settings (language, theme...).","anchor":"network"},{"id":"v1.0-user-99-glossary-2","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"99-glossary","chapterTitle":"Glossary","heading":"Customer","snippet":"Organization (company, association, public service...) to whom you grant access to your platform. End users log in within the context of a Customer.","anchor":"customer"},{"id":"v1.0-user-99-glossary-3","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"99-glossary","chapterTitle":"Glossary","heading":"Application","snippet":"Service or digital product hosted and distributed via WakaStart. It is attached to a Partner and can be deployed for several Networks and Customers.","anchor":"application"},{"id":"v1.0-user-99-glossary-4","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"99-glossary","chapterTitle":"Glossary","heading":"Profile","snippet":"A set of rights grouped under a name (e.g., \"Billing Manager\"). One or more Profiles are assigned to a user to give them access to the corresponding features.","anchor":"profile"},{"id":"v1.0-user-99-glossary-5","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"99-glossary","chapterTitle":"Glossary","heading":"Team","snippet":"Group of users within the same Customer, with a collective access level. Useful for organizing access by department or function.","anchor":"team"},{"id":"v1.0-user-99-glossary-6","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"99-glossary","chapterTitle":"Glossary","heading":"API Key","snippet":"Secure identifier that lets an external tool interact with WakaStart without going through the web interface. Associated with a user and an application.","anchor":"api-key"},{"id":"v1.0-user-99-glossary-7","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"99-glossary","chapterTitle":"Glossary","heading":"Administration levels","snippet":"The roles that define what a user can do on the platform:\n\n| Level | What it allows |\n|--------|----------------|\n| **WakaAdmin** | Full access to the entire platform and infrastructure |\n| **OwnerAdm","anchor":"administration-levels"},{"id":"v1.0-user-99-glossary-8","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"99-glossary","chapterTitle":"Glossary","heading":"Application rights","snippet":"Fine-grained permissions granted via Profiles:\n\n| Right | What it allows |\n|-------|----------------|\n| **Billing** | Access the billing and credits section |\n| **Configuration** | Access the applicat","anchor":"application-rights"},{"id":"v1.0-user-99-glossary-9","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"99-glossary","chapterTitle":"Glossary","heading":"Team levels","snippet":"Within a Team, each member has a level: Admin, Manager, Member, Contributor, Reader, or None.","anchor":"team-levels"},{"id":"v1.0-user-99-glossary-10","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"99-glossary","chapterTitle":"Glossary","heading":"HDS Roles","snippet":"Roles specific to the health data context, assigned to users who need access to HDS features: HDS Administrator, Patient, Healthcare Professional, HDS Storage, HDS Deletion, Medical Access.","anchor":"hds-roles"},{"id":"v1.0-user-99-glossary-11","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"99-glossary","chapterTitle":"Glossary","heading":"Common statuses","snippet":"Platform elements (Partners, Networks, Customers, Applications...) have a status among: **Active**, **Inactive**, **Suspended**, **Deleted**, **Draft**.","anchor":"common-statuses"},{"id":"v1.0-user-99-glossary-12","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"99-glossary","chapterTitle":"Glossary","heading":"Global filter","snippet":"The contextual navigation bar present at the top of every page. It lets you restrict the display to a specific Partner, Network, and/or Customer.","anchor":"global-filter"},{"id":"v1.0-user-99-glossary-13","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"99-glossary","chapterTitle":"Glossary","heading":"Blueprint (backup file)","snippet":"File describing the complete configuration of an application. Can be exported from WakaStart and re-imported to duplicate or restore an environment.","anchor":"blueprint-backup-file"},{"id":"v1.0-user-99-glossary-14","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"99-glossary","chapterTitle":"Glossary","heading":"Stellar","snippet":"Public, decentralized blockchain used by WakaStart to anchor digital fingerprints of your audit logs, ensuring they cannot be tampered with after the fact.","anchor":"stellar"},{"id":"v1.0-user-99-glossary-15","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"99-glossary","chapterTitle":"Glossary","heading":"Harbor","snippet":"Application image registry used by WakaStart to store and distribute deployable packages. Comparable to a warehouse of ready-to-use packages for each application.","anchor":"harbor"},{"id":"v1.0-user-99-glossary-16","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"99-glossary","chapterTitle":"Glossary","heading":"OpenBao","snippet":"The platform's digital vault, which securely stores the credentials, keys, and certificates needed for services to function.","anchor":"openbao"},{"id":"v1.0-user-99-glossary-17","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"99-glossary","chapterTitle":"Glossary","heading":"Credits","snippet":"WakaStart's internal currency. Every action on the platform (sending an email, processing a file, generating a document...) consumes a certain number of credits.","anchor":"credits"},{"id":"v1.0-user-99-glossary-18","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"99-glossary","chapterTitle":"Glossary","heading":"HDS (Health Data Hosting)","snippet":"French certification governing the storage and processing of personal health data. WakaStart offers a dedicated module for organizations subject to this regulation.","anchor":"hds-health-data-hosting"},{"id":"v1.0-user-99-glossary-19","version":"v1.0","sectionId":"user","sectionLabel":"User","chapterId":"99-glossary","chapterTitle":"Glossary","heading":"SSO (Single Sign-On)","snippet":"Single sign-on: a mechanism that lets a user log in to WakaStart with their existing corporate credentials (Google Workspace, Microsoft 365, Okta...).","anchor":"sso-single-sign-on"},{"id":"v1.0-dev-01-architecture-0","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"01-architecture","chapterTitle":"Architecture","heading":"Why this step","snippet":"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 ","anchor":"why-this-step"},{"id":"v1.0-dev-01-architecture-1","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"01-architecture","chapterTitle":"Architecture","heading":"Multi-tenant hierarchy","snippet":"WakaStart organizes entities top to bottom:\n\n```\nPartner\n └── App ←── the Wakapp connects here\n └── Network (1 realm Keycloak)\n └── Customer\n ├── User\n ","anchor":"multi-tenant-hierarchy"},{"id":"v1.0-dev-01-architecture-2","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"01-architecture","chapterTitle":"Architecture","heading":"Where the WakaApp sits in the ecosystem","snippet":"```\n ┌──────────────────────────────────────────┐\n │ PLATEFORME WAKASTART │\n │ │\n ┌──────────","anchor":"where-the-wakaapp-sits-in-the-ecosystem"},{"id":"v1.0-dev-01-architecture-3","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"01-architecture","chapterTitle":"Architecture","heading":"The two public APIs consumed by a Wakapp","snippet":"| API | When | Endpoint examples |\n|-----|-------|----------------------|\n| **Discovery API** | **Before** authentication | `POST /discover/start-login`, `GET /discover/subdomain`, `GET /discover/emai","anchor":"the-two-public-apis-consumed-by-a-wakapp"},{"id":"v1.0-dev-01-architecture-4","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"01-architecture","chapterTitle":"Architecture","heading":"Stack on the Wakastart side vs. the WakaApp side","snippet":"| Aspect | WakaStart platform | Your WakaApp |\n|--------|---------------------|---------------|\n| Auth | Keycloak OAuth2 PKCE | Implement the PKCE flow (see chapter 3) |\n| Enriched token | Managed by ","anchor":"stack-on-the-wakastart-side-vs-the-wakaapp-side"},{"id":"v1.0-dev-01-architecture-5","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"01-architecture","chapterTitle":"Architecture","heading":"Two access modes","snippet":"| Mode | Usage | Required header(s) |\n|------|-------|-----------------|\n| **JWT Bearer + enriched** | User-facing apps (proxied frontend) | `Authorization: Bearer ` + `x-enriched-toke","anchor":"two-access-modes"},{"id":"v1.0-dev-01-architecture-6","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"01-architecture","chapterTitle":"Architecture","heading":"Communication flow (overview)","snippet":"```\n1. [PREAAUTH] Wakapp → API Discovery : POST /discover/start-login\n → URL Keycloak retournée\n Wakapp → Keycloak : redirect navigateur","anchor":"communication-flow-overview"},{"id":"v1.0-dev-01-architecture-7","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"01-architecture","chapterTitle":"Architecture","heading":"Best practices","snippet":"- Store tokens in **HttpOnly cookies** (never in localStorage).\n- Use **WIDs** in your URLs and logs — UUIDs are internal.\n- Never inspect or verify the signature of the `x-enriched-token` on the Waka","anchor":"best-practices"},{"id":"v1.0-dev-01-architecture-8","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"01-architecture","chapterTitle":"Architecture","heading":"Learn more","snippet":"- [Discovery — Identifying the user](02-discovery): the first call before auth\n- [Authentication — OAuth2 PKCE](03-authentication-overview): the full flow\n- [Using the API](10-api-conventions): header","anchor":"learn-more"},{"id":"v1.0-dev-02-discovery-0","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"02-discovery","chapterTitle":"Discovery — Identifying the user","heading":"Why this step","snippet":"Before any OAuth2 authentication, your Wakapp needs to know **which Keycloak realm** to redirect the user to. In a multi-tenant architecture, each Network has its own realm. Discovery resolves this ma","anchor":"why-this-step"},{"id":"v1.0-dev-02-discovery-1","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"02-discovery","chapterTitle":"Discovery — Identifying the user","heading":"Key concepts","snippet":"- **Subdomain**: short string identifying a Network or Customer (`app.test`, `acme-prod`). May contain dots.\n- **WID**: short identifier (6 alphanumeric chars) used for entities (`NET001`, `ACM001`).\n","anchor":"key-concepts"},{"id":"v1.0-dev-02-discovery-2","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"02-discovery","chapterTitle":"Discovery — Identifying the user","heading":"The 3 available patterns","snippet":"","anchor":"the-3-available-patterns"},{"id":"v1.0-dev-02-discovery-3","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"02-discovery","chapterTitle":"Discovery — Identifying the user","heading":"Pattern 1 — `start-login` by hostname (recommended)","snippet":"The recommended flow for single-tenant Wakapps. Discovery automatically resolves the Keycloak `client_id` from the hostname.\n\n```http\nPOST {DISCOVERY_API_URL}/discover/start-login\nContent-Type: applic","anchor":"pattern-1-start-login-by-hostname-recommended"},{"id":"v1.0-dev-02-discovery-4","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"02-discovery","chapterTitle":"Discovery — Identifying the user","heading":"Pattern 2 — `start-login` by email (Microsoft-style)","snippet":"The user enters their email. Discovery identifies their organization and returns the same `keycloakUrl`.\n\n```http\nPOST {DISCOVERY_API_URL}/discover/start-login\nContent-Type: application/json\n\n{\n \"ema","anchor":"pattern-2-start-login-by-email-microsoft-style"},{"id":"v1.0-dev-02-discovery-5","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"02-discovery","chapterTitle":"Discovery — Identifying the user","heading":"Pattern 3 — Direct lookup (informational)","snippet":"To display information before login (logo, organization name, IDP type) or after login for the app catalog.\n\n```http\nGET /discover/email?email=john@acme.com\n```\n\n```json\n{\n \"users\": [{\n \"user_emai","anchor":"pattern-3-direct-lookup-informational"},{"id":"v1.0-dev-02-discovery-6","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"02-discovery","chapterTitle":"Discovery — Identifying the user","heading":"Lookup by subdomain","snippet":"```http\nGET /discover/subdomain?subdomain=acme-prod\n```\n\n```json\n{\n \"subdomain\": \"acme-prod\",\n \"result\": {\n \"type\": \"network\",\n \"network_wid\": \"NET001\",\n \"network_subdomain\": \"acme-prod\",\n ","anchor":"lookup-by-subdomain"},{"id":"v1.0-dev-02-discovery-7","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"02-discovery","chapterTitle":"Discovery — Identifying the user","heading":"Application lookup","snippet":"```http\nGET /discover/apps/customer?customerId={uuid_or_wid}\nGET /discover/apps/user?userId={uuid}\nGET /discover/apps/network?networkId={uuid}\n```\n\nReturns the applications accessible for a given enti","anchor":"application-lookup"},{"id":"v1.0-dev-02-discovery-8","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"02-discovery","chapterTitle":"Discovery — Identifying the user","heading":"Extracting the subdomain","snippet":"The subdomain can be **multi-label** (contains dots). Naming convention:\n\n```\n{subdomain}.{platform-domain}\n app.test.wakastart.app\n └──┬───┘ └──────┬─────┘\n subdomain platform domain\n```\n\n","anchor":"extracting-the-subdomain"},{"id":"v1.0-dev-02-discovery-9","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"02-discovery","chapterTitle":"Discovery — Identifying the user","heading":"Subdomain vs. email — when to use which","snippet":"| Criterion | `host` (hostname) | `email` |\n|---------|-------------------|---------|\n| Single-tenant Wakapp | Recommended | Not necessary |\n| Multi-tenant portal | Not suitable | Recommended |\n| The ","anchor":"subdomain-vs-email-when-to-use-which"},{"id":"v1.0-dev-02-discovery-10","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"02-discovery","chapterTitle":"Discovery — Identifying the user","heading":"Anti-enumeration and throttling","snippet":"> [!WARNING]\n> Anti-enumeration is **not** uniform across the entire service. `POST /discover/start-login` and the `/internal/*` routes normalize the latency of negative responses. `GET /discover/emai","anchor":"anti-enumeration-and-throttling"},{"id":"v1.0-dev-02-discovery-11","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"02-discovery","chapterTitle":"Discovery — Identifying the user","heading":"Error handling","snippet":"| Status | Body | Cause | Action |\n|--------|------|-------|--------|\n| `400` | `invalid_request` | `email` + `host` provided simultaneously, or neither | Check the body |\n| `400` | `invalid_request` ","anchor":"error-handling"},{"id":"v1.0-dev-02-discovery-12","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"02-discovery","chapterTitle":"Discovery — Identifying the user","heading":"Best practices","snippet":"- Call `start-login` only once per login attempt — do not automatically retry on `404`.\n- Extract the subdomain from `window.location.hostname` using the `extractSubdomain` function, never hardcode it","anchor":"best-practices"},{"id":"v1.0-dev-02-discovery-13","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"02-discovery","chapterTitle":"Discovery — Identifying the user","heading":"Common pitfalls","snippet":"- **Incorrect subdomain extraction**: sending `host=\"app\"` instead of `host=\"app.test\"` → `404 not_found`. See the `extractSubdomain` function above.\n- **Hardcoded `appId`**: do not send `appId` unles","anchor":"common-pitfalls"},{"id":"v1.0-dev-02-discovery-14","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"02-discovery","chapterTitle":"Discovery — Identifying the user","heading":"Learn more","snippet":"- [Authentication — OAuth2 PKCE](03-authentication-overview): using the `keycloakUrl` returned by `start-login`\n- [Common pitfalls](17-pitfalls): diagnosing frequent Discovery errors","anchor":"learn-more"},{"id":"v1.0-dev-03-authentication-overview-0","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"03-authentication-overview","chapterTitle":"Authentication — Concepts & Flow","heading":"Why this step","snippet":"Authentication is the most critical flow of your integration. A poorly implemented flow exposes you to vulnerabilities (code interception, CSRF, token leakage). PKCE (`Proof Key for Code Exchange`) is","anchor":"why-this-step"},{"id":"v1.0-dev-03-authentication-overview-1","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"03-authentication-overview","chapterTitle":"Authentication — Concepts & Flow","heading":"Key concepts","snippet":"- **code_verifier**: random 43-128 char string, generated client-side, stored in sessionStorage.\n- **code_challenge**: `BASE64URL(SHA256(code_verifier))`, sent to Keycloak.\n- **access_token**: RS256 J","anchor":"key-concepts"},{"id":"v1.0-dev-03-authentication-overview-2","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"03-authentication-overview","chapterTitle":"Authentication — Concepts & Flow","heading":"Complete flow in 10 steps","snippet":"```mermaid\nsequenceDiagram\n participant F as Wakapp Frontend\n participant B as Wakapp Backend\n participant D as Discovery\n participant K as Keycloak\n participant BFF as BFF (enrich)\n\n F->>F: Gén","anchor":"complete-flow-in-10-steps"},{"id":"v1.0-dev-03-authentication-overview-3","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"03-authentication-overview","chapterTitle":"Authentication — Concepts & Flow","heading":"Keycloak prerequisites — OIDC client","snippet":"For the flow to work, the OIDC client must be configured as follows:\n\n| Parameter | Value | Reason |\n|-----------|--------|--------|\n| **Client ID** | Value of `apps.client_id` in the DB (auto-generat","anchor":"keycloak-prerequisites-oidc-client"},{"id":"v1.0-dev-03-authentication-overview-4","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"03-authentication-overview","chapterTitle":"Authentication — Concepts & Flow","heading":"Keycloak Organizations (IAM-C4 — mandatory)","snippet":"The WakaStart authentication service rejects any Keycloak token without the `organization` claim. Three conditions must be met:\n\n**1. Realm — Organizations feature enabled**\n```\nConsole Keycloak → rea","anchor":"keycloak-organizations-iam-c4-mandatory"},{"id":"v1.0-dev-03-authentication-overview-5","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"03-authentication-overview","chapterTitle":"Authentication — Concepts & Flow","heading":"Error handling at the callback","snippet":"| Case | Symptom | Solution |\n|-----|----------|----------|\n| `redirect_uri` mismatch | `400 Invalid redirect_uri` from Keycloak | Check the exact URI match in the Keycloak console |\n| Incorrect `clie","anchor":"error-handling-at-the-callback"},{"id":"v1.0-dev-03-authentication-overview-6","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"03-authentication-overview","chapterTitle":"Authentication — Concepts & Flow","heading":"Learn more","snippet":"- [PKCE Implementation](04-authentication-implementation): full step-by-step code\n- [Discovery](02-discovery): `start-login` and extracting the `keycloakUrl`\n- [User context /me](05-me-endpoint-payloa","anchor":"learn-more"},{"id":"v1.0-dev-04-authentication-implementation-0","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"04-authentication-implementation","chapterTitle":"Authentication — PKCE Implementation","heading":"Step 2 — PKCE generation (TypeScript)","snippet":"```typescript\n// Génération du code_verifier (43-128 chars URL-safe)\nfunction generateCodeVerifier(): string {\n const array = new Uint8Array(32);\n crypto.getRandomValues(array);\n return btoa(String","anchor":"step-2-pkce-generation-typescript"},{"id":"v1.0-dev-04-authentication-implementation-1","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"04-authentication-implementation","chapterTitle":"Authentication — PKCE Implementation","heading":"Step 3 — Calling `start-login`","snippet":"```http\nPOST {DISCOVERY_API_URL}/discover/start-login\nContent-Type: application/json\n\n{\n \"host\": \"app.test\",\n \"redirectUri\": \"https://app.test.wakastart.app/api/auth/callback\",\n \"state\": \"550e8400-","anchor":"step-3-calling-start-login"},{"id":"v1.0-dev-04-authentication-implementation-2","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"04-authentication-implementation","chapterTitle":"Authentication — PKCE Implementation","heading":"Step 4 — Extraction and storage","snippet":"```typescript\nconst { keycloakUrl } = await startLoginResponse.json();\n\nconst parsed = new URL(keycloakUrl);\nconst realm = parsed.pathname.match(/\\/realms\\/([^/]+)\\//)?.[1];\nconst clientId = parsed","anchor":"step-4-extraction-and-storage"},{"id":"v1.0-dev-04-authentication-implementation-3","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"04-authentication-implementation","chapterTitle":"Authentication — PKCE Implementation","heading":"Step 7 — Exchanging the code for tokens (callback)","snippet":"```typescript\n// Handler côté serveur (route /api/auth/callback)\nconst realm = sessionStorage.getItem(\"login_realm\");\nconst clientId = sessionStorage.getItem(\"login_client_id\");\nconst verifier ","anchor":"step-7-exchanging-the-code-for-tokens-callback"},{"id":"v1.0-dev-04-authentication-implementation-4","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"04-authentication-implementation","chapterTitle":"Authentication — PKCE Implementation","heading":"Step 8 — Mandatory enrichment","snippet":"```http\nPOST {WAKASTART_BACKEND_URL}/api/auth/enrich\nAuthorization: Bearer {access_token}\n```\n\n**Response:**\n```json\n{\n \"token\": \"eyJhbGciOiJIUzI1NiJ9...\",\n \"payload\": {\n \"adminLevel\": \"CustomerA","anchor":"step-8-mandatory-enrichment"},{"id":"v1.0-dev-04-authentication-implementation-5","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"04-authentication-implementation","chapterTitle":"Authentication — PKCE Implementation","heading":"Step 9 — Storing the cookies","snippet":"```typescript\n// Côté serveur Next.js (route handler ou middleware)\nimport { cookies } from \"next/headers\";\n\nconst cookieStore = await cookies();\n\n// access_token Keycloak RS256\ncookieStore.set(\"keycl","anchor":"step-9-storing-the-cookies"},{"id":"v1.0-dev-04-authentication-implementation-6","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"04-authentication-implementation","chapterTitle":"Authentication — PKCE Implementation","heading":"Proactive refresh","snippet":"```http\nPOST /api/auth/token/refresh\nContent-Type: application/json\n\n{ \"refreshToken\": \"xxx\", \"accessToken\": \"xxx\" }\n```\n\n**Response:** new `access_token`, `refresh_token`, `enriched_token`.\n\n**Recomm","anchor":"proactive-refresh"},{"id":"v1.0-dev-04-authentication-implementation-7","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"04-authentication-implementation","chapterTitle":"Authentication — PKCE Implementation","heading":"Logout","snippet":"```http\nPOST /api/auth/logout\nContent-Type: application/json\n\n{ \"refreshToken\": \"xxx\" }\n```\n\nInvalidates the refresh token on the Keycloak side. **Complete it on the frontend side:**\n\n```typescript\n//","anchor":"logout"},{"id":"v1.0-dev-04-authentication-implementation-8","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"04-authentication-implementation","chapterTitle":"Authentication — PKCE Implementation","heading":"Best practices","snippet":"- Always generate a new `code_verifier` for every login attempt.\n- Verify the CSRF `state` on return from the callback (compare sessionStorage vs. query param).\n- Store tokens **only** in HttpOnly coo","anchor":"best-practices"},{"id":"v1.0-dev-04-authentication-implementation-9","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"04-authentication-implementation","chapterTitle":"Authentication — PKCE Implementation","heading":"Common pitfalls","snippet":"- **Infinite refresh loop**: on `401`, attempt the refresh only once, then redirect to login.\n- **`redirect_uri` with a trailing slash**: `https://app.test/callback` ≠ `https://app.test/callback/`.\n- ","anchor":"common-pitfalls"},{"id":"v1.0-dev-04-authentication-implementation-10","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"04-authentication-implementation","chapterTitle":"Authentication — PKCE Implementation","heading":"Learn more","snippet":"- [Discovery](02-discovery): `start-login` and extracting the `keycloakUrl`\n- [User context /me](05-me-endpoint-payload): post-auth step\n- [Common pitfalls](17-pitfalls): diagnosing authentication err","anchor":"learn-more"},{"id":"v1.0-dev-05-me-endpoint-payload-0","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"05-me-endpoint-payload","chapterTitle":"User context — /me payload structure","heading":"Why this step matters","snippet":"The Keycloak JWT contains minimal identity (sub, email, admin levels). But to build a conditional UI (hide/show buttons based on rights, display the correct organization name, etc.), you need the comp","anchor":"why-this-step-matters"},{"id":"v1.0-dev-05-me-endpoint-payload-1","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"05-me-endpoint-payload","chapterTitle":"User context — /me payload structure","heading":"Key concepts","snippet":"- **adminLevel**: the user's hierarchical admin level (WakaAdmin → None).\n- **appRights**: list of `resource.action`-type application rights accumulated from profiles. Details of the actual shape (`pr","anchor":"key-concepts"},{"id":"v1.0-dev-05-me-endpoint-payload-2","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"05-me-endpoint-payload","chapterTitle":"User context — /me payload structure","heading":"Call","snippet":"```http\nGET /api/me\nAuthorization: Bearer \nx-enriched-token: \n```\n\nBoth headers are required. The response is the same whether the caller uses a Bearer JWT or a","anchor":"call"},{"id":"v1.0-dev-05-me-endpoint-payload-3","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"05-me-endpoint-payload","chapterTitle":"User context — /me payload structure","heading":"Full response","snippet":"```json\n{\n \"id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"wid\": \"WKST05\",\n \"email\": \"john@acme.com\",\n \"firstName\": \"John\",\n \"lastName\": \"Doe\",\n \"keycloakId\": \"kc-550e8400-e29b-41d4-a716-4466554","anchor":"full-response"},{"id":"v1.0-dev-05-me-endpoint-payload-4","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"05-me-endpoint-payload","chapterTitle":"User context — /me payload structure","heading":"Description of each field","snippet":"","anchor":"description-of-each-field"},{"id":"v1.0-dev-05-me-endpoint-payload-5","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"05-me-endpoint-payload","chapterTitle":"User context — /me payload structure","heading":"Identity","snippet":"| Field | Type | Description |\n|-------|------|-------------|\n| `id` | UUID | Internal database identifier |\n| `wid` | string | Short identifier (6 chars) for URLs |\n| `email` | string | User's email ","anchor":"identity"},{"id":"v1.0-dev-05-me-endpoint-payload-6","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"05-me-endpoint-payload","chapterTitle":"User context — /me payload structure","heading":"Access levels","snippet":"| Field | Type | Description |\n|-------|------|-------------|\n| `adminLevel` | string | Hierarchical admin level (see table below) |\n\n> The `userLevel` field **is no longer returned by `/me`** — it ha","anchor":"access-levels"},{"id":"v1.0-dev-05-me-endpoint-payload-7","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"05-me-endpoint-payload","chapterTitle":"User context — /me payload structure","heading":"Multi-tenant context","snippet":"| Field | Type | Description |\n|-------|------|-------------|\n| `customer` | object | Customer the user belongs to |\n| `partner` | object | Parent partner of the customer |\n| `network` | object | Pare","anchor":"multi-tenant-context"},{"id":"v1.0-dev-05-me-endpoint-payload-8","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"05-me-endpoint-payload","chapterTitle":"User context — /me payload structure","heading":"HDS roles","snippet":"| Field | Type | Description |\n|-------|------|-------------|\n| `hdsRoles` | string[] | HDS (Healthcare Data Security) roles: `HDS_ADMIN`, `HDS_PATIENT`, etc. |\n\n> The `wakaRoles` field (cross-cutting","anchor":"hds-roles"},{"id":"v1.0-dev-05-me-endpoint-payload-9","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"05-me-endpoint-payload","chapterTitle":"User context — /me payload structure","heading":"Teams","snippet":"`appRights` within the team context is a free-form field encoded on the team (distinct from the user's global `appRights`).","anchor":"teams"},{"id":"v1.0-dev-05-me-endpoint-payload-10","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"05-me-endpoint-payload","chapterTitle":"User context — /me payload structure","heading":"Profiles and application rights","snippet":"- `profiles`: assigned profiles. A profile = a set of `AppRight`s in the DB.\n- `appRights`: deduplicated and merged array of all rights coming from all profiles. Format: `{resource}.{action}`.\n- `feat","anchor":"profiles-and-application-rights"},{"id":"v1.0-dev-05-me-endpoint-payload-11","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"05-me-endpoint-payload","chapterTitle":"User context — /me payload structure","heading":"What's in /me vs in the JWT","snippet":"> [!WARNING]\n> The enriched JWT (wakaToken) is signed and must fit under the 4 KB cookie limit. Several claims that used to be present have been removed from it and are now available **only** via `/me","anchor":"whats-in-me-vs-in-the-jwt"},{"id":"v1.0-dev-05-me-endpoint-payload-12","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"05-me-endpoint-payload","chapterTitle":"User context — /me payload structure","heading":"Go further","snippet":"- [/me cache and invalidation](06-me-endpoint-caching): when to call `/me`, caching, invalidation\n- [Access control](07-access-control-model): how to use `appRights` in your guards\n- [Using the API](1","anchor":"go-further"},{"id":"v1.0-dev-06-me-endpoint-caching-0","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"06-me-endpoint-caching","chapterTitle":"User context — Cache & Invalidation","heading":"When to call /me","snippet":"| Situation | Call /me? |\n|-----------|:-------------:|\n| **At login** (after enrichment) | Yes — store in the context |\n| After a **token refresh** | Yes — rights may have changed |\n| On every **navi","anchor":"when-to-call-me"},{"id":"v1.0-dev-06-me-endpoint-caching-1","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"06-me-endpoint-caching","chapterTitle":"User context — Cache & Invalidation","heading":"Recommended React pattern — AuthContext","snippet":"```typescript\n// lib/auth-context.tsx\nimport { createContext, useContext, useState, useCallback } from \"react\";\n\ninterface MeUser {\n id: string;\n wid: string;\n email: string;\n firstName: string;\n ","anchor":"recommended-react-pattern-authcontext"},{"id":"v1.0-dev-06-me-endpoint-caching-2","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"06-me-endpoint-caching","chapterTitle":"User context — Cache & Invalidation","heading":"Caching and recommended TTL","snippet":"`/me` is called once at login. The response remains stable as long as:\n- The user's rights haven't been modified by an admin.\n- The token hasn't been refreshed.\n\n**Recommended strategy:**\n1. Store it ","anchor":"caching-and-recommended-ttl"},{"id":"v1.0-dev-06-me-endpoint-caching-3","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"06-me-endpoint-caching","chapterTitle":"User context — Cache & Invalidation","heading":"Synchronization after token refresh","snippet":"```typescript\n// app/api/auth/refresh/route.ts\nexport async function POST(req: NextRequest) {\n const cookieStore = await cookies();\n const refreshToken = cookieStore.get(\"refresh_token\")?.value;\n\n ","anchor":"synchronization-after-token-refresh"},{"id":"v1.0-dev-06-me-endpoint-caching-4","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"06-me-endpoint-caching","chapterTitle":"User context — Cache & Invalidation","heading":"Best practices","snippet":"- Do not store the `/me` payload in `localStorage` — it contains sensitive rights.\n- Use `appRights` only for **conditional display** on the front end. The backend is the source of authority.\n- If `ad","anchor":"best-practices"},{"id":"v1.0-dev-06-me-endpoint-caching-5","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"06-me-endpoint-caching","chapterTitle":"User context — Cache & Invalidation","heading":"Common pitfalls","snippet":"- **Stale rights**: rights are modified by an admin but the `/me` cache isn't invalidated. Add a lightweight polling mechanism or a WebSocket notification.\n- **Empty `appRights` but active user**: the","anchor":"common-pitfalls"},{"id":"v1.0-dev-06-me-endpoint-caching-6","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"06-me-endpoint-caching","chapterTitle":"User context — Cache & Invalidation","heading":"Go further","snippet":"- [Access control](07-access-control-model): how to use `appRights` in your guards\n- [Using the API](10-api-conventions): how to pass tokens in your requests","anchor":"go-further"},{"id":"v1.0-dev-07-access-control-model-0","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"07-access-control-model","chapterTitle":"Access control — Model & Cascade","heading":"Key concepts","snippet":"- **adminLevel**: hierarchical level, determines the scope of CRUD operations.\n- **appRights**: fine-grained rights on specific resources (`users.create`, `infra.deploy`…), derived from profiles. The ","anchor":"key-concepts"},{"id":"v1.0-dev-07-access-control-model-1","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"07-access-control-model","chapterTitle":"Access control — Model & Cascade","heading":"The 2 rights vectors","snippet":"","anchor":"the-2-rights-vectors"},{"id":"v1.0-dev-07-access-control-model-2","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"07-access-control-model","chapterTitle":"Access control — Model & Cascade","heading":"1. `adminLevel` — hierarchical scope","snippet":"Controls **who can see and modify what** based on their position in the multi-tenant hierarchy.\n\n```\nWakaAdmin → Everything (whole platform, all Partners)\nOwnerAdmin → Everything (Partner owner","anchor":"1-adminlevel-hierarchical-scope"},{"id":"v1.0-dev-07-access-control-model-3","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"07-access-control-model","chapterTitle":"Access control — Model & Cascade","heading":"2. `appRights` — fine-grained application rights","snippet":"Rights of type `{resource}.{action}` accumulated from the user's profiles.\n\n**Format:** `resource.action` or `resource.sub-resource.action`\n\nExamples:\n```\npartners.read users.create ","anchor":"2-apprights-fine-grained-application-rights"},{"id":"v1.0-dev-07-access-control-model-4","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"07-access-control-model","chapterTitle":"Access control — Model & Cascade","heading":"Feature cascade","snippet":"A feature must be enabled at **three levels** to be available:\n\n```mermaid\nflowchart TD\n A[\"AppFeature.isEnabled = true\"] --> D{AND}\n B[\"NetworkAppFeature.isEnabled = true\"] --> D\n C[\"CustomerAppFe","anchor":"feature-cascade"},{"id":"v1.0-dev-07-access-control-model-5","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"07-access-control-model","chapterTitle":"Access control — Model & Cascade","heading":"Combined check via `/token/authorize`","snippet":"For complex checks (admin level + role + right) in a single call:\n\n```http\nPOST /api/token/authorize\nx-api-key: sk_live_...\nContent-Type: application/json\n\n{\n \"token\": \"eyJ...\",\n \"checks\": {\n \"ad","anchor":"combined-check-via-tokenauthorize"},{"id":"v1.0-dev-07-access-control-model-6","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"07-access-control-model","chapterTitle":"Access control — Model & Cascade","heading":"Best practices","snippet":"- **Principle of least privilege**: only grant the rights strictly necessary in profiles.\n- **Backend = authority**: always verify rights on the server side. The frontend only hides.\n- **Fine granular","anchor":"best-practices"},{"id":"v1.0-dev-07-access-control-model-7","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"07-access-control-model","chapterTitle":"Access control — Model & Cascade","heading":"Common pitfalls","snippet":"- **Confusing three neighboring concepts**: `adminLevel` (`ADMIN`, `TEAM`, `INVITE`, `USER`, `EXTERN`, `NONE`) is the administrative scope over the hierarchy; `teamLevel` (`ADMIN`, `MANAGER`, `MEMBER`","anchor":"common-pitfalls"},{"id":"v1.0-dev-07-access-control-model-8","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"07-access-control-model","chapterTitle":"Access control — Model & Cascade","heading":"Go further","snippet":"- [Guards & hooks implementation](08-access-control-implementation): full frontend and backend code\n- [Feature flags and cascade](09-access-control-features): AppFeature, NetworkAppFeature, CustomerAp","anchor":"go-further"},{"id":"v1.0-dev-08-access-control-implementation-0","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"08-access-control-implementation","chapterTitle":"Access control — Guards & Hooks","heading":"Frontend implementation","snippet":"","anchor":"frontend-implementation"},{"id":"v1.0-dev-08-access-control-implementation-1","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"08-access-control-implementation","chapterTitle":"Access control — Guards & Hooks","heading":"`useAppRights` hook","snippet":"```typescript\n// hooks/use-app-rights.ts\nimport { useAuth } from \"@/lib/auth-context\";\n\nexport function useAppRights() {\n const { user } = useAuth();\n const appRights = user?.appRights ?? [];\n\n ret","anchor":"useapprights-hook"},{"id":"v1.0-dev-08-access-control-implementation-2","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"08-access-control-implementation","chapterTitle":"Access control — Guards & Hooks","heading":"`` component","snippet":"```typescript\n// components/protected.tsx\nimport { useAppRights } from \"@/hooks/use-app-rights\";\n\ninterface ProtectedProps {\n right?: string;\n anyRight?: string[];\n allRights?: string[];\n adminLev","anchor":"protected-component"},{"id":"v1.0-dev-08-access-control-implementation-3","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"08-access-control-implementation","chapterTitle":"Access control — Guards & Hooks","heading":"Backend implementation with NestJS (in your Wakapp)","snippet":"If your Wakapp has its own backend, check rights by **delegating to** WakaStart's authorization API: `POST /api/token/authorize`.\n\n> **Do not do this** — Never verify the `x-enriched-token` signature ","anchor":"backend-implementation-with-nestjs-in-your-wakapp"},{"id":"v1.0-dev-08-access-control-implementation-4","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"08-access-control-implementation","chapterTitle":"Access control — Guards & Hooks","heading":"`@RequireAppRight` decorator","snippet":"```typescript\n// decorators/require-app-right.decorator.ts\nimport { SetMetadata } from \"@nestjs/common\";\n\nexport const REQUIRED_RIGHT_KEY = \"requiredRight\";\nexport const RequireAppRight = (right: stri","anchor":"requireappright-decorator"},{"id":"v1.0-dev-08-access-control-implementation-5","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"08-access-control-implementation","chapterTitle":"Access control — Guards & Hooks","heading":"`AppRightGuard` — delegation to `/api/token/authorize`","snippet":"```typescript\n// guards/app-right.guard.ts\nimport { Injectable, CanActivate, ExecutionContext, ForbiddenException } from \"@nestjs/common\";\nimport { Reflector } from \"@nestjs/core\";\nimport { REQUIRED_R","anchor":"apprightguard-delegation-to-apitokenauthorize"},{"id":"v1.0-dev-08-access-control-implementation-6","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"08-access-control-implementation","chapterTitle":"Access control — Guards & Hooks","heading":"Usage in a NestJS controller","snippet":"```typescript\n@Controller(\"users\")\n@UseGuards(AppRightGuard)\nexport class UsersController {\n @Post()\n @RequireAppRight(\"users.create\")\n async createUser(@Body() dto: CreateUserDto) {\n // ...\n }","anchor":"usage-in-a-nestjs-controller"},{"id":"v1.0-dev-08-access-control-implementation-7","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"08-access-control-implementation","chapterTitle":"Access control — Guards & Hooks","heading":"Best practices","snippet":"- **Log denials**: log `403`s with the missing right (but never the full token).\n- **Cache invalidation**: after a profile change by an admin, the user must re-login or call `/me` again.","anchor":"best-practices"},{"id":"v1.0-dev-08-access-control-implementation-8","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"08-access-control-implementation","chapterTitle":"Access control — Guards & Hooks","heading":"Go further","snippet":"- [Feature flags and cascade](09-access-control-features): AppFeature, NetworkAppFeature, CustomerAppFeature\n- [/me user context](05-me-endpoint-payload): source of rights\n- [Endpoint reference](14-en","anchor":"go-further"},{"id":"v1.0-dev-09-access-control-features-0","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"09-access-control-features","chapterTitle":"Access control — Feature Flags","heading":"Cascade model","snippet":"A feature is the result of three independent activations. If **even one** is `false`, the feature is unavailable to the user:\n\n```mermaid\nflowchart LR\n A[\"App\\nAppFeature.isEnabled\"] -->|AND| D[\"Feat","anchor":"cascade-model"},{"id":"v1.0-dev-09-access-control-features-1","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"09-access-control-features","chapterTitle":"Access control — Feature Flags","heading":"Standard platform features","snippet":"| Feature | Description |\n|---------|-------------|\n| `invitations` | User invitation flow (email sending, acceptance, provisioning) |\n| `antivirus` | Antivirus scanning of uploaded files (ClamAV via ","anchor":"standard-platform-features"},{"id":"v1.0-dev-09-access-control-features-2","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"09-access-control-features","chapterTitle":"Access control — Feature Flags","heading":"Frontend usage","snippet":"","anchor":"frontend-usage"},{"id":"v1.0-dev-09-access-control-features-3","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"09-access-control-features","chapterTitle":"Access control — Feature Flags","heading":"Simple check","snippet":"```typescript\nimport { useEffect, useState } from \"react\";\nimport { useAuth } from \"@/lib/auth-context\";\n\nfunction InvitationsSection() {\n const { user } = useAuth();\n const [enabled, setEnabled] = ","anchor":"simple-check"},{"id":"v1.0-dev-09-access-control-features-4","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"09-access-control-features","chapterTitle":"Access control — Feature Flags","heading":"Combining feature + right","snippet":"```tsx\n// Resolve the feature upstream (see example above), then combine with the right:\n{enabled && (\n \n \n \n)}\n```\n\n> **Reco","anchor":"combining-feature-right"},{"id":"v1.0-dev-09-access-control-features-5","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"09-access-control-features","chapterTitle":"Access control — Feature Flags","heading":"Activation via the API","snippet":"The actual endpoints live under `/api/config/app-features` — there is no dedicated route per `customerWid`/`appWid` + feature name:\n\n```http\nGET /api/config/app-features/check/{customerWid}/{featureCo","anchor":"activation-via-the-api"},{"id":"v1.0-dev-09-access-control-features-6","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"09-access-control-features","chapterTitle":"Access control — Feature Flags","heading":"NestJS backend guard — RequireFeature","snippet":"If your Wakapp exposes endpoints that require an active feature:\n\n```typescript\n// decorators/require-feature.decorator.ts\nimport { SetMetadata } from \"@nestjs/common\";\n\nexport const REQUIRED_FEATURE_","anchor":"nestjs-backend-guard-requirefeature"},{"id":"v1.0-dev-09-access-control-features-7","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"09-access-control-features","chapterTitle":"Access control — Feature Flags","heading":"Best practices","snippet":"- **Check the feature before rendering the UI**: don't wait for the API's `403` to hide a button.\n- **No feature enabled by default**: if `GET app-features/check/...` returns `enabled: false` (or if t","anchor":"best-practices"},{"id":"v1.0-dev-09-access-control-features-8","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"09-access-control-features","chapterTitle":"Access control — Feature Flags","heading":"Common pitfalls","snippet":"- **Missing feature ≠ error**: if `app-features/enabled/{customerWid}` returns an empty array, it's not a bug — the customer simply has no feature enabled.\n- **Don't confuse feature and AppRight**: an","anchor":"common-pitfalls"},{"id":"v1.0-dev-09-access-control-features-9","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"09-access-control-features","chapterTitle":"Access control — Feature Flags","heading":"Go further","snippet":"- [Rights model](07-access-control-model): adminLevel, appRights\n- [Invitations](18-invitations-create): full example combining feature + right","anchor":"go-further"},{"id":"v1.0-dev-12-best-practices-security-0","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"12-best-practices-security","chapterTitle":"Best Practices — Security","heading":"1. Tokens in HttpOnly cookies only","snippet":"```typescript\n// GOOD: HttpOnly cookie, never accessible from JavaScript\ncookieStore.set(\"keycloak_token\", token, { httpOnly: true, secure: true });\n\n// BAD: accessible from JS, vulnerable to XSS\nloca","anchor":"1-tokens-in-httponly-cookies-only"},{"id":"v1.0-dev-12-best-practices-security-1","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"12-best-practices-security","chapterTitle":"Best Practices — Security","heading":"2. PKCE mandatory — no implicit flow","snippet":"The implicit flow (`response_type=token`) is deprecated and forbidden. PKCE S256 is the only supported flow.","anchor":"2-pkce-mandatory-no-implicit-flow"},{"id":"v1.0-dev-12-best-practices-security-2","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"12-best-practices-security","chapterTitle":"Best Practices — Security","heading":"3. No client-side secrets","snippet":"```typescript\n// GOOD: API key in a server-side env variable\nconst apiKey = process.env.WAKASTART_API_KEY; // server-only\n\n// BAD: exposed in the frontend bundle\nconst apiKey = \"sk_live_...\"; // visib","anchor":"3-no-client-side-secrets"},{"id":"v1.0-dev-12-best-practices-security-3","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"12-best-practices-security","chapterTitle":"Best Practices — Security","heading":"4. Backend always verifies, frontend only hides","snippet":"```typescript\n// GOOD on the NestJS Wakapp backend side\n@UseGuards(AppRightGuard)\n@RequireAppRight(\"users.delete\")\nasync deleteUser(@Param(\"id\") id: string) { ... }\n\n// GOOD on the frontend side (UI h","anchor":"4-backend-always-verifies-frontend-only-hides"},{"id":"v1.0-dev-12-best-practices-security-4","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"12-best-practices-security","chapterTitle":"Best Practices — Security","heading":"5. Generic error messages on login","snippet":"```typescript\n// GOOD: does not reveal whether the email is known\ncatch (err) {\n setError(\"Unable to log in. Check your credentials and try again.\");\n}\n\n// BAD: reveals the account's existence\ncatch ","anchor":"5-generic-error-messages-on-login"},{"id":"v1.0-dev-12-best-practices-security-5","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"12-best-practices-security","chapterTitle":"Best Practices — Security","heading":"6. HTTPS in production, hardened CSP","snippet":"```typescript\n// next.config.ts\nconst securityHeaders = [\n { key: \"Strict-Transport-Security\", value: \"max-age=63072000; includeSubDomains; preload\" },\n { key: \"X-Content-Type-Options\", value: \"nosn","anchor":"6-https-in-production-hardened-csp"},{"id":"v1.0-dev-12-best-practices-security-6","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"12-best-practices-security","chapterTitle":"Best Practices — Security","heading":"7. Never log tokens","snippet":"```typescript\n// GOOD: redact the Authorization header in logs\nlogger.info(\"API call\", {\n url: apiUrl,\n headers: { ...headers, Authorization: \"[REDACTED]\", \"x-enriched-token\": \"[REDACTED]\" },\n});\n\n/","anchor":"7-never-log-tokens"},{"id":"v1.0-dev-12-best-practices-security-7","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"12-best-practices-security","chapterTitle":"Best Practices — Security","heading":"8. Never hold `INTERNAL_API_SECRET`","snippet":"This secret is only used between internal Wakastellar services. No third-party Wakapp needs it, and never will.\n\n---","anchor":"8-never-hold-internal_api_secret"},{"id":"v1.0-dev-12-best-practices-security-8","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"12-best-practices-security","chapterTitle":"Best Practices — Security","heading":"Handling 401, 403, 429 errors","snippet":"```typescript\nasync function apiFetch(url: string, options: RequestInit) {\n const res = await fetch(url, options);\n\n switch (res.status) {\n case 401:\n // Token expired → try refresh, then re","anchor":"handling-401-403-429-errors"},{"id":"v1.0-dev-12-best-practices-security-9","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"12-best-practices-security","chapterTitle":"Best Practices — Security","heading":"Security testing","snippet":"","anchor":"security-testing"},{"id":"v1.0-dev-12-best-practices-security-10","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"12-best-practices-security","chapterTitle":"Best Practices — Security","heading":"21. Never test against production","snippet":"Use a dedicated test Customer (with `CUSTOMER_WID=TST001`) and a test App.","anchor":"21-never-test-against-production"},{"id":"v1.0-dev-12-best-practices-security-11","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"12-best-practices-security","chapterTitle":"Best Practices — Security","heading":"22. Mock Discovery and enrich responses in unit tests","snippet":"```typescript\n// jest.setup.ts\njest.mock(\"@/lib/api/discovery\", () => ({\n startLogin: jest.fn().mockResolvedValue({\n keycloakUrl: \"https://auth.test/realms/test/protocol/openid-connect/auth?client","anchor":"22-mock-discovery-and-enrich-responses-in-unit-tests"},{"id":"v1.0-dev-12-best-practices-security-12","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"12-best-practices-security","chapterTitle":"Best Practices — Security","heading":"23. Integration tests with a service account","snippet":"For e2e tests, use a dedicated API key (`sk_test_...`) with minimal rights.\n\n---","anchor":"23-integration-tests-with-a-service-account"},{"id":"v1.0-dev-12-best-practices-security-13","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"12-best-practices-security","chapterTitle":"Best Practices — Security","heading":"Pre-production security checklist","snippet":"- [ ] Tokens stored in HttpOnly cookies (never localStorage)\n- [ ] Server-side proxy implemented (the browser does not contact the API directly)\n- [ ] PKCE S256 (no implicit flow)\n- [ ] HTTPS with HST","anchor":"pre-production-security-checklist"},{"id":"v1.0-dev-12-best-practices-security-14","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"12-best-practices-security","chapterTitle":"Best Practices — Security","heading":"Going further","snippet":"- [Performance & Observability](13-best-practices-perf-observability): cache, retry, metrics, tracing\n- [Common pitfalls](17-pitfalls): diagnosing frequent errors","anchor":"going-further"},{"id":"v1.0-dev-13-best-practices-perf-observability-0","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"13-best-practices-perf-observability","chapterTitle":"Best Practices — Performance & Observability","heading":"Performance","snippet":"","anchor":"performance"},{"id":"v1.0-dev-13-best-practices-perf-observability-1","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"13-best-practices-perf-observability","chapterTitle":"Best Practices — Performance & Observability","heading":"9. Cache /me — a single call at login","snippet":"```typescript\n// GOOD: store in a React context, never re-fetch on navigation\nconst AuthProvider = ({ children }) => {\n const [user, setUser] = useState(null);\n\n useEffect(() => {\n // Called only","anchor":"9-cache-me-a-single-call-at-login"},{"id":"v1.0-dev-13-best-practices-perf-observability-2","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"13-best-practices-perf-observability","chapterTitle":"Best Practices — Performance & Observability","heading":"10. Proactive refresh before expiration","snippet":"```typescript\n// GOOD: check exp - now < 60s and refresh before expiration\nconst REFRESH_THRESHOLD = 60; // seconds\n\nfunction scheduleTokenRefresh(expiresIn: number) {\n const refreshIn = Math.max(0, ","anchor":"10-proactive-refresh-before-expiration"},{"id":"v1.0-dev-13-best-practices-perf-observability-3","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"13-best-practices-perf-observability","chapterTitle":"Best Practices — Performance & Observability","heading":"11. Pagination — never load everything","snippet":"```typescript\n// GOOD: paginate, max limit = 100\nconst { data } = await apiGet(\"config/users\", { page: \"1\", limit: \"50\" });\n\n// BAD: try to load everything\nconst { data } = await apiGet(\"config/users\"","anchor":"11-pagination-never-load-everything"},{"id":"v1.0-dev-13-best-practices-perf-observability-4","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"13-best-practices-perf-observability","chapterTitle":"Best Practices — Performance & Observability","heading":"12. TanStack Query — staleTime suited to criticality","snippet":"```typescript\n// Data that rarely changes (branding, runtime-config): 5 minutes\nuseQuery({\n queryKey: [\"runtime-config\"],\n queryFn: fetchRuntimeConfig,\n staleTime: 5 * 60 * 1000,\n});\n\n// Data that ","anchor":"12-tanstack-query-staletime-suited-to-criticality"},{"id":"v1.0-dev-13-best-practices-perf-observability-5","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"13-best-practices-perf-observability","chapterTitle":"Best Practices — Performance & Observability","heading":"Architecture","snippet":"","anchor":"architecture"},{"id":"v1.0-dev-13-best-practices-perf-observability-6","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"13-best-practices-perf-observability","chapterTitle":"Best Practices — Performance & Observability","heading":"13. Server-side proxy for all API calls","snippet":"The browser must never call the Public API directly.\n\n```\nBrowser → /api/proxy/[...path] (Next.js route) → Public API\n └── reads HttpOnly cookies\n └── adds Authorization + x-","anchor":"13-server-side-proxy-for-all-api-calls"},{"id":"v1.0-dev-13-best-practices-perf-observability-7","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"13-best-practices-perf-observability","chapterTitle":"Best Practices — Performance & Observability","heading":"14. Separate Discovery and API","snippet":"```typescript\n// GOOD: Discovery used only once, before auth\nconst { keycloakUrl } = await discoverStartLogin({ host });\nwindow.location.assign(keycloakUrl);\n\n// BAD: calling Discovery after every log","anchor":"14-separate-discovery-and-api"},{"id":"v1.0-dev-13-best-practices-perf-observability-8","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"13-best-practices-perf-observability","chapterTitle":"Best Practices — Performance & Observability","heading":"15. Respect the hierarchy in your data model","snippet":"```typescript\n// Your entities should reflect the Wakastart hierarchy\ninterface AppContext {\n partnerId: string; // pid from the wakaToken\n networkId: string; // nid\n customerId: string; // cid\n ","anchor":"15-respect-the-hierarchy-in-your-data-model"},{"id":"v1.0-dev-13-best-practices-perf-observability-9","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"13-best-practices-perf-observability","chapterTitle":"Best Practices — Performance & Observability","heading":"16. Use WIDs in URLs","snippet":"```\nGOOD: /users/WKST05 (readable, stable)\nBAD : /users/550e8400-... (internal UUID)\n```\n\n---","anchor":"16-use-wids-in-urls"},{"id":"v1.0-dev-13-best-practices-perf-observability-10","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"13-best-practices-perf-observability","chapterTitle":"Best Practices — Performance & Observability","heading":"Observability","snippet":"","anchor":"observability"},{"id":"v1.0-dev-13-best-practices-perf-observability-11","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"13-best-practices-perf-observability","chapterTitle":"Best Practices — Performance & Observability","heading":"17. Propagate `x-trace-id`","snippet":"```typescript\n// Include the trace ID in all your API requests\nconst traceId = crypto.randomUUID();\nheaders[\"x-trace-id\"] = traceId;\n\n// Log on the frontend side with the same ID\nlogger.info(\"API call","anchor":"17-propagate-x-trace-id"},{"id":"v1.0-dev-13-best-practices-perf-observability-12","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"13-best-practices-perf-observability","chapterTitle":"Best Practices — Performance & Observability","heading":"18. Recommended metrics","snippet":"Expose Prometheus metrics from your Wakapp:\n\n```\nwakapp_api_calls_total{endpoint, status}\nwakapp_token_refresh_total{success}\nwakapp_invitations_created_total{customer}\nwakapp_invitations_accepted_tot","anchor":"18-recommended-metrics"},{"id":"v1.0-dev-13-best-practices-perf-observability-13","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"13-best-practices-perf-observability","chapterTitle":"Best Practices — Performance & Observability","heading":"19. Structured logging","snippet":"```typescript\n// GOOD: structured JSON, parsable by Loki / CloudWatch\nlogger.info({\n event: \"user_login_success\",\n userId: user.wid,\n customerId: user.customer.wid,\n adminLevel: user.adminLevel,\n ","anchor":"19-structured-logging"},{"id":"v1.0-dev-13-best-practices-perf-observability-14","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"13-best-practices-perf-observability","chapterTitle":"Best Practices — Performance & Observability","heading":"Pre-production performance checklist","snippet":"- [ ] Proactive refresh implemented (60s threshold)\n- [ ] Rate limit handled (exponential backoff)\n- [ ] /me loaded once, cached, invalidated on refresh\n- [ ] runtime-config loaded once at startup\n- [","anchor":"pre-production-performance-checklist"},{"id":"v1.0-dev-13-best-practices-perf-observability-15","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"13-best-practices-perf-observability","chapterTitle":"Best Practices — Performance & Observability","heading":"Going further","snippet":"- [Headers & Rate limits](11-api-headers-rate-limits): exponential backoff in detail\n- [Common pitfalls](17-pitfalls): diagnosing performance issues","anchor":"going-further"},{"id":"v1.0-dev-17-pitfalls-0","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"17-pitfalls","chapterTitle":"Common integration pitfalls","heading":"1. \"No realm is associated with this subdomain\"","snippet":"**Symptom:** `start-login` returns `404 not_found`.\n\n| Cause | Diagnosis | Solution |\n|-------|-----------|----------|\n| Incorrect subdomain extraction | Discovery logs: `host=\"app\"` instead of `\"app.","anchor":"1-no-realm-is-associated-with-this-subdomain"},{"id":"v1.0-dev-17-pitfalls-1","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"17-pitfalls","chapterTitle":"Common integration pitfalls","heading":"2. \"Invalid client or Invalid client credentials\" on callback","snippet":"**Symptom:** The `/api/auth/callback` POST handler returns `401` with this Keycloak message.\n\n| Cause | Diagnosis | Solution |\n|-------|-----------|----------|\n| OIDC client in `Client authentication:","anchor":"2-invalid-client-or-invalid-client-credentials-on-callback"},{"id":"v1.0-dev-17-pitfalls-2","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"17-pitfalls","chapterTitle":"Common integration pitfalls","heading":"3. \"Missing enriched token\" on every API call","snippet":"**Symptom:** The user is logged in (cookies exist, `/me` responds), but every proxied call to downstream services returns `401 Missing or invalid enriched token`.\n\n| Cause | Diagnosis | Solution |\n|--","anchor":"3-missing-enriched-token-on-every-api-call"},{"id":"v1.0-dev-17-pitfalls-3","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"17-pitfalls","chapterTitle":"Common integration pitfalls","heading":"4. `organization` claim absent — empty dashboard","snippet":"**Symptom:** The user logs in without error, but the dashboard has no rights and `/me` returns `appRights: []`.\n\n**Cause:** The Keycloak token does not contain the `organization` claim required by the","anchor":"4-organization-claim-absent-empty-dashboard"},{"id":"v1.0-dev-17-pitfalls-4","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"17-pitfalls","chapterTitle":"Common integration pitfalls","heading":"5. `sameSite: strict` cookie blocks the session on return from Keycloak","snippet":"**Symptom:** After the Keycloak redirect to `/api/auth/callback`, cookies are not transmitted. The handler cannot read `pkce_verifier` or the session cookies. The user is redirected in a loop back to ","anchor":"5-samesite-strict-cookie-blocks-the-session-on-return-from-keycloak"},{"id":"v1.0-dev-17-pitfalls-5","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"17-pitfalls","chapterTitle":"Common integration pitfalls","heading":"6. Container Next.js build fails — EACCES on `.next/cache/images`","snippet":"**Symptom:**\n```\nError: EACCES: permission denied, mkdir '/app/.next/cache/images'\n```\n\n**Cause:** The `COPY .next ./.next` in the Dockerfile doesn't transfer the correct permissions to the container'","anchor":"6-container-nextjs-build-fails-eacces-on-nextcacheimages"},{"id":"v1.0-dev-17-pitfalls-6","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"17-pitfalls","chapterTitle":"Common integration pitfalls","heading":"7. Rate limit triggered on Discovery during initial integration","snippet":"**Symptom:** After a few quick tests, the Discovery service responds `429` to every request.\n\n**Cause:** During integration, developers call `start-login` in a loop to debug. The 5 req/s limit is hit ","anchor":"7-rate-limit-triggered-on-discovery-during-initial-integration"},{"id":"v1.0-dev-17-pitfalls-7","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"17-pitfalls","chapterTitle":"Common integration pitfalls","heading":"8. `redirect_uri` with a trailing slash","snippet":"**Symptom:** `400 invalid_redirect_uri` during the token exchange with Keycloak.\n\n**Cause:** Keycloak compares the callback URI **exactly** (sensitive to the trailing `/` and to casing).\n\n| Configured","anchor":"8-redirect_uri-with-a-trailing-slash"},{"id":"v1.0-dev-17-pitfalls-8","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"17-pitfalls","chapterTitle":"Common integration pitfalls","heading":"9. Empty `appRights` despite an assigned profile","snippet":"**Symptom:** `GET /me` returns `appRights: []` but the user does have a profile assigned, visible in the admin UI.\n\n**Causes and diagnostics:**\n\n| Cause | Diagnosis | Solution |\n|-------|-----------|-","anchor":"9-empty-apprights-despite-an-assigned-profile"},{"id":"v1.0-dev-17-pitfalls-9","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"17-pitfalls","chapterTitle":"Common integration pitfalls","heading":"10. Email with uppercase letters causes a `404 not_found` on Discovery","snippet":"**Symptom:** Lookup by email returns `{ users: [] }` for `John@Acme.com` even though the user exists with `john@acme.com`.\n\n**Cause:** Discovery normalizes emails to **lowercase** before searching. Th","anchor":"10-email-with-uppercase-letters-causes-a-404-not_found-on-discovery"},{"id":"v1.0-dev-17-pitfalls-10","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"17-pitfalls","chapterTitle":"Common integration pitfalls","heading":"Summary — Debugging checklist","snippet":"When things aren't working, in order:\n\n1. **`start-login` returns `404`** → check `extractSubdomain`, check `network.subdomain` in the DB\n2. **`Invalid client` on callback** → `Client authentication: ","anchor":"summary-debugging-checklist"},{"id":"v1.0-dev-17-pitfalls-11","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"17-pitfalls","chapterTitle":"Common integration pitfalls","heading":"Go further","snippet":"- [Common errors — HTTP](15-errors-http): exact HTTP codes and messages\n- [Authentication — implementation](04-authentication-implementation): full flow with code\n- [Endpoint reference](14-endpoint-re","anchor":"go-further"},{"id":"v1.0-dev-10-api-conventions-0","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"10-api-conventions","chapterTitle":"Using the API — REST Conventions","heading":"Key concepts","snippet":"- **Bearer + enriched**: dual authentication required for frontend calls.\n- **API Key**: alternative for server-to-server backends.\n- **WID**: short identifier preferred in URLs and parameters.\n- **Au","anchor":"key-concepts"},{"id":"v1.0-dev-10-api-conventions-1","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"10-api-conventions","chapterTitle":"Using the API — REST Conventions","heading":"Request authentication","snippet":"","anchor":"request-authentication"},{"id":"v1.0-dev-10-api-conventions-2","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"10-api-conventions","chapterTitle":"Using the API — REST Conventions","heading":"Method 1 — Bearer JWT + enriched token (frontend)","snippet":"A request to downstream services **must** carry **two** tokens:\n\n```http\nAuthorization: Bearer (RS256, émis par Keycloak)\nx-enriched-token: (gér","anchor":"method-1-bearer-jwt-enriched-token-frontend"},{"id":"v1.0-dev-10-api-conventions-3","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"10-api-conventions","chapterTitle":"Using the API — REST Conventions","heading":"Method 2 — API Key (server-to-server backend)","snippet":"API Keys entirely replace the Bearer+enriched pair. They are scoped to a Customer.\n\n```typescript\nconst response = await fetch(`${WAKASTART_API_URL}/api/config/users`, {\n headers: {\n \"x-api-key\": ","anchor":"method-2-api-key-server-to-server-backend"},{"id":"v1.0-dev-10-api-conventions-4","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"10-api-conventions","chapterTitle":"Using the API — REST Conventions","heading":"REST conventions","snippet":"| Convention | Detail |\n|-----------|--------|\n| **HTTP verbs** | `GET` (read), `POST` (create), `PATCH` (partial update), `PUT` (replace), `DELETE` (delete) |\n| **Date format** | ISO 8601 with timezo","anchor":"rest-conventions"},{"id":"v1.0-dev-10-api-conventions-5","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"10-api-conventions","chapterTitle":"Using the API — REST Conventions","heading":"Unified error format","snippet":"```json\n{\n \"statusCode\": 403,\n \"message\": \"Niveau d'administration insuffisant. Requis: CustomerAdmin, Actuel: User\",\n \"error\": \"Forbidden\"\n}\n```\n\nFor validation errors (400):\n\n```json\n{\n \"statusC","anchor":"unified-error-format"},{"id":"v1.0-dev-10-api-conventions-6","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"10-api-conventions","chapterTitle":"Using the API — REST Conventions","heading":"Pagination","snippet":"All list endpoints support page-based pagination:\n\n```http\nGET /api/config/users?page=1&limit=20\n```\n\n```json\n{\n \"data\": [\n { \"id\": \"uuid\", \"wid\": \"WKST05\", \"email\": \"john@acme.com\" }\n ],\n \"meta","anchor":"pagination"},{"id":"v1.0-dev-10-api-conventions-7","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"10-api-conventions","chapterTitle":"Using the API — REST Conventions","heading":"Common filters","snippet":"```http\nGET /api/config/users?search=john&isActive=true&page=1&limit=20\nGET /api/config/customers?networkId=NET001&page=1\nGET /api/invitations/sent?status=PENDING&page=1&limit=10\n```\n\n---","anchor":"common-filters"},{"id":"v1.0-dev-10-api-conventions-8","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"10-api-conventions","chapterTitle":"Using the API — REST Conventions","heading":"Automatic multi-tenancy","snippet":"Data is **automatically filtered** according to the token scope:\n\n| `adminLevel` | Scope of returned data |\n|-------------|------------------------------|\n| `WakaAdmin` | The entire platform |\n| `Owne","anchor":"automatic-multi-tenancy"},{"id":"v1.0-dev-10-api-conventions-9","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"10-api-conventions","chapterTitle":"Using the API — REST Conventions","heading":"Runtime config","snippet":"To load your app's theme, languages, and branding in a single call:\n\n```http\nGET /api/apps/{appWid}/runtime-config\nAuthorization: Bearer \nx-enriched-token: \n```\n\n```json\n{\n \"theme\":","anchor":"runtime-config"},{"id":"v1.0-dev-10-api-conventions-10","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"10-api-conventions","chapterTitle":"Using the API — REST Conventions","heading":"Best practices","snippet":"- **Server proxy**: never let the browser handle cookies or tokens directly.\n- **Handling 401s**: attempt a token refresh, then redirect to login. Never an infinite loop.\n- **Prefer WIDs**: in your ro","anchor":"best-practices"},{"id":"v1.0-dev-10-api-conventions-11","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"10-api-conventions","chapterTitle":"Using the API — REST Conventions","heading":"Common pitfalls","snippet":"- **Missing `x-enriched-token` header**: all frontend requests return `401`.\n- **Unnecessary manual filtering**: manually adding `customerId=xxx` when the backend already filters.\n- **`limit=1000`**: ","anchor":"common-pitfalls"},{"id":"v1.0-dev-10-api-conventions-12","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"10-api-conventions","chapterTitle":"Using the API — REST Conventions","heading":"Go further","snippet":"- [Headers & Rate limits](11-api-headers-rate-limits): required headers, idempotence, CORS, throttling\n- [Endpoint reference](14-endpoint-reference): full table of all routes\n- [HTTP errors](15-errors","anchor":"go-further"},{"id":"v1.0-dev-11-api-headers-rate-limits-0","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"11-api-headers-rate-limits","chapterTitle":"API Usage — Headers & Rate Limits","heading":"Required headers","snippet":"","anchor":"required-headers"},{"id":"v1.0-dev-11-api-headers-rate-limits-1","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"11-api-headers-rate-limits","chapterTitle":"API Usage — Headers & Rate Limits","heading":"Frontend calls (Bearer + enriched)","snippet":"```http\nAuthorization: Bearer \nx-enriched-token: \nContent-Type: application/json\n```","anchor":"frontend-calls-bearer-enriched"},{"id":"v1.0-dev-11-api-headers-rate-limits-2","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"11-api-headers-rate-limits","chapterTitle":"API Usage — Headers & Rate Limits","heading":"Backend calls (API Key)","snippet":"```http\nx-api-key: sk_live_...\nContent-Type: application/json\n```\n\n---","anchor":"backend-calls-api-key"},{"id":"v1.0-dev-11-api-headers-rate-limits-3","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"11-api-headers-rate-limits","chapterTitle":"API Usage — Headers & Rate Limits","heading":"Optional headers","snippet":"| Header | Description |\n|--------|-------------|\n| `Accept-Language` | Preferred language for error messages (`fr`, `en`). |\n\n> **No `x-trace-id`/`x-request-id`**: these headers are not implemented t","anchor":"optional-headers"},{"id":"v1.0-dev-11-api-headers-rate-limits-4","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"11-api-headers-rate-limits","chapterTitle":"API Usage — Headers & Rate Limits","heading":"CORS","snippet":"The WakaStart API supports CORS for registered origins. The rules:\n\n- **Allowed origins**: configured in `ALLOWED_ORIGINS` on the API side.\n- **Credentials**: `Access-Control-Allow-Credentials: true` ","anchor":"cors"},{"id":"v1.0-dev-11-api-headers-rate-limits-5","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"11-api-headers-rate-limits","chapterTitle":"API Usage — Headers & Rate Limits","heading":"Idempotency","snippet":"`GET`, `PUT`, and `DELETE` operations are idempotent. For `POST`:\n\n- **Invitation creation**: if a `PENDING` invitation already exists for the same email + Customer, the API responds `409 Conflict`. I","anchor":"idempotency"},{"id":"v1.0-dev-11-api-headers-rate-limits-6","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"11-api-headers-rate-limits","chapterTitle":"API Usage — Headers & Rate Limits","heading":"Rate limiting","snippet":"The API applies three levels of throttling:\n\n| Level | TTL | Limit | Description |\n|--------|-----|--------|-------------|\n| Short | 1,000 ms | 10 req | Immediate anti-burst |\n| Medium | 60,000 ms | 1","anchor":"rate-limiting"},{"id":"v1.0-dev-11-api-headers-rate-limits-7","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"11-api-headers-rate-limits","chapterTitle":"API Usage — Headers & Rate Limits","heading":"Endpoint-specific limits","snippet":"| Endpoint | Limit |\n|----------|--------|\n| `POST /discover/start-login` | 5/60s · 20/600s (10 min) · 100/3600s (1 h) |\n| `POST /api/auth/enrich` | Not limited on the BFF side (no guard/throttler on ","anchor":"endpoint-specific-limits"},{"id":"v1.0-dev-11-api-headers-rate-limits-8","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"11-api-headers-rate-limits","chapterTitle":"API Usage — Headers & Rate Limits","heading":"Exponential backoff","snippet":"```typescript\nasync function fetchWithRetry(\n url: string,\n options: RequestInit,\n maxRetries = 3\n): Promise {\n for (let attempt = 0; attempt < maxRetries; attempt++) {\n const res = a","anchor":"exponential-backoff"},{"id":"v1.0-dev-11-api-headers-rate-limits-9","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"11-api-headers-rate-limits","chapterTitle":"API Usage — Headers & Rate Limits","heading":"Checking rights from your backend","snippet":"```http\nPOST /api/token/authorize\nx-api-key: sk_live_...\nContent-Type: application/json\n\n{\n \"token\": \"eyJ...\",\n \"checks\": {\n \"adminLevel\": { \"requiredLevel\": \"CustomerAdmin\" },\n \"roles\": { \"ro","anchor":"checking-rights-from-your-backend"},{"id":"v1.0-dev-11-api-headers-rate-limits-10","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"11-api-headers-rate-limits","chapterTitle":"API Usage — Headers & Rate Limits","heading":"Best practices","snippet":"- **Headers don't stack**: a call with both `x-api-key` AND `Authorization: Bearer` will see the API key take precedence.\n- **Log the error response body** on 5xx (route, method, `statusCode`, `messag","anchor":"best-practices"},{"id":"v1.0-dev-11-api-headers-rate-limits-11","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"11-api-headers-rate-limits","chapterTitle":"API Usage — Headers & Rate Limits","heading":"Common pitfalls","snippet":"- **Parallel calls to refresh**: if several requests expire at the same time and all attempt a simultaneous refresh, only one succeeds. Implement a client-side mutex.\n- **Rate limit on tests**: in CI,","anchor":"common-pitfalls"},{"id":"v1.0-dev-11-api-headers-rate-limits-12","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"11-api-headers-rate-limits","chapterTitle":"API Usage — Headers & Rate Limits","heading":"Go further","snippet":"- [HTTP errors](15-errors-http): `429` and `401` codes in detail\n- [Security best practices](12-best-practices-security): tokens, secrets, HTTPS","anchor":"go-further"},{"id":"v1.0-dev-14-endpoint-reference-0","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"14-endpoint-reference","chapterTitle":"Endpoint reference","heading":"Discovery (pre-auth — public)","snippet":"Base URL: `{DISCOVERY_API_URL}` (default: `http://localhost`)\n\n| Method | Route | Throttle | Description |\n|---------|-------|----------|-------------|\n| `GET` | `/discover/email?email=` | 5/60s · 20/","anchor":"discovery-pre-auth-public"},{"id":"v1.0-dev-14-endpoint-reference-1","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"14-endpoint-reference","chapterTitle":"Endpoint reference","heading":"Auth (wakastart BFF — public for enrich)","snippet":"Base URL: `{WAKASTART_BACKEND_URL}` (default: `http://localhost`)\n\n| Method | Route | Throttle | Description |\n|---------|-------|----------|-------------|\n| `GET` | `/api/auth/public-key` | — | Publi","anchor":"auth-wakastart-bff-public-for-enrich"},{"id":"v1.0-dev-14-endpoint-reference-2","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"14-endpoint-reference","chapterTitle":"Endpoint reference","heading":"Profile & Rights (Public API)","snippet":"Base URL: `{PUBLIC_API_URL}` (default: `http://localhost`)\nAuth: `Authorization: Bearer` + `x-enriched-token` **or** `x-api-key`\n\n| Method | Route | Required right | Description |\n|---------|-------|:","anchor":"profile-rights-public-api"},{"id":"v1.0-dev-14-endpoint-reference-3","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"14-endpoint-reference","chapterTitle":"Endpoint reference","heading":"Config — Partners","snippet":"| Method | Route | Required right | Description |\n|---------|-------|:------------:|-------------|\n| `GET` | `/api/config/partners` | `partners.read` | List partners |\n| `GET` | `/api/config/partners/","anchor":"config-partners"},{"id":"v1.0-dev-14-endpoint-reference-4","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"14-endpoint-reference","chapterTitle":"Endpoint reference","heading":"Config — Networks","snippet":"| Method | Route | Required right | Description |\n|---------|-------|:------------:|-------------|\n| `GET` | `/api/config/networks` | `networks.read` | List networks |\n| `GET` | `/api/config/networks/","anchor":"config-networks"},{"id":"v1.0-dev-14-endpoint-reference-5","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"14-endpoint-reference","chapterTitle":"Endpoint reference","heading":"Config — Customers","snippet":"| Method | Route | Required right | Description |\n|---------|-------|:------------:|-------------|\n| `GET` | `/api/config/customers` | `customers.read` | List customers |\n| `GET` | `/api/config/custom","anchor":"config-customers"},{"id":"v1.0-dev-14-endpoint-reference-6","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"14-endpoint-reference","chapterTitle":"Endpoint reference","heading":"Config — Users","snippet":"| Method | Route | Required right | Description |\n|---------|-------|:------------:|-------------|\n| `GET` | `/api/config/users` | `users.read` | List users |\n| `GET` | `/api/config/users/:wid` | `use","anchor":"config-users"},{"id":"v1.0-dev-14-endpoint-reference-7","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"14-endpoint-reference","chapterTitle":"Endpoint reference","heading":"Config — Teams","snippet":"| Method | Route | Required right | Description |\n|---------|-------|:------------:|-------------|\n| `GET` | `/api/config/teams` | `teams.read` | List teams |\n| `GET` | `/api/config/teams/:wid` | `tea","anchor":"config-teams"},{"id":"v1.0-dev-14-endpoint-reference-8","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"14-endpoint-reference","chapterTitle":"Endpoint reference","heading":"Config — Applications","snippet":"| Method | Route | Required right | Description |\n|---------|-------|:------------:|-------------|\n| `GET` | `/api/config/apps` | `apps.read` | List applications |\n| `GET` | `/api/config/apps/:wid` | ","anchor":"config-applications"},{"id":"v1.0-dev-14-endpoint-reference-9","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"14-endpoint-reference","chapterTitle":"Endpoint reference","heading":"Config — Profiles and Rights","snippet":"| Method | Route | Required right | Description |\n|---------|-------|:------------:|-------------|\n| `GET` | `/api/config/profiles` | `profiles.read` | List profiles |\n| `GET` | `/api/config/profiles/","anchor":"config-profiles-and-rights"},{"id":"v1.0-dev-14-endpoint-reference-10","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"14-endpoint-reference","chapterTitle":"Endpoint reference","heading":"Invitations","snippet":"| Method | Route | Auth | Required right | Description |\n|---------|-------|:----:|:------------:|-------------|\n| `POST` | `/api/invitations` | Bearer / API key | `invitations.create` | Create an inv","anchor":"invitations"},{"id":"v1.0-dev-14-endpoint-reference-11","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"14-endpoint-reference","chapterTitle":"Endpoint reference","heading":"API Keys","snippet":"| Method | Route | Required right | Description |\n|---------|-------|:------------:|-------------|\n| `GET` | `/api/config/api-keys` | `api-keys.read` | List API keys |\n| `GET` | `/api/config/api-keys/","anchor":"api-keys"},{"id":"v1.0-dev-14-endpoint-reference-12","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"14-endpoint-reference","chapterTitle":"Endpoint reference","heading":"Audit Logs","snippet":"| Method | Route | Required right | Description |\n|---------|-------|:------------:|-------------|\n| `GET` | `/api/audit/logs` | `audit.read` | List audit logs (paginated, filterable) |\n| `GET` | `/ap","anchor":"audit-logs"},{"id":"v1.0-dev-14-endpoint-reference-13","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"14-endpoint-reference","chapterTitle":"Endpoint reference","heading":"Antivirus","snippet":"| Method | Route | Required right | Description |\n|---------|-------|:------------:|-------------|\n| `POST` | `/api/antivirus/scans` | `antivirus.scan` | Submit a file for scanning (multipart, max 100","anchor":"antivirus"},{"id":"v1.0-dev-14-endpoint-reference-14","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"14-endpoint-reference","chapterTitle":"Endpoint reference","heading":"Backup & Import","snippet":"| Method | Route | Required right | Description |\n|---------|-------|:------------:|-------------|\n| `GET` | `/api/backup/applications/:wid` | `apps.read` | JSON export of an application |\n| `GET` | `","anchor":"backup-import"},{"id":"v1.0-dev-14-endpoint-reference-15","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"14-endpoint-reference","chapterTitle":"Endpoint reference","heading":"Translations & Themes","snippet":"| Method | Route | Required right | Description |\n|---------|-------|:------------:|-------------|\n| `GET` | `/api/translations` | — | List translation keys |\n| `POST` | `/api/ai-translation/bulk` | `","anchor":"translations-themes"},{"id":"v1.0-dev-14-endpoint-reference-16","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"14-endpoint-reference","chapterTitle":"Endpoint reference","heading":"MCP Server (Claude Code Integration)","snippet":"| Method | Route | Auth | Description |\n|---------|-------|:----:|-------------|\n| `POST` | `/api/mcp` | None (public docs) | JSON-RPC 2.0 endpoint, 5 tools available |\n\n**Available MCP tools:**\n\n| To","anchor":"mcp-server-claude-code-integration"},{"id":"v1.0-dev-15-errors-http-0","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"15-errors-http","chapterTitle":"Errors — HTTP Codes","heading":"Unified error format","snippet":"```json\n{\n \"statusCode\": 403,\n \"message\": \"Niveau d'administration insuffisant. Requis: CustomerAdmin, Actuel: User\",\n \"error\": \"Forbidden\"\n}\n```\n\nFor validation errors (`400`) with several invalid","anchor":"unified-error-format"},{"id":"v1.0-dev-15-errors-http-1","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"15-errors-http","chapterTitle":"Errors — HTTP Codes","heading":"400 — Bad Request","snippet":"Invalid data. The body did not pass DTO validation.\n\n**Common causes:**\n- Invalid email\n- Disposable-domain email (yopmail, mailinator…)\n- Missing or malformed UUID\n- Required field missing\n- Value ou","anchor":"400-bad-request"},{"id":"v1.0-dev-15-errors-http-2","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"15-errors-http","chapterTitle":"Errors — HTTP Codes","heading":"401 — Unauthorized","snippet":"Missing or invalid authentication.","anchor":"401-unauthorized"},{"id":"v1.0-dev-15-errors-http-3","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"15-errors-http","chapterTitle":"Errors — HTTP Codes","heading":"Case 1 — Missing enriched token","snippet":"```json\n{\n \"statusCode\": 401,\n \"message\": \"Token enrichi manquant ou invalide\",\n \"error\": \"Unauthorized\"\n}\n```\n\n**Causes:**\n1. `x-enriched-token` header absent — check the server-side proxy\n2. `wak","anchor":"case-1-missing-enriched-token"},{"id":"v1.0-dev-15-errors-http-4","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"15-errors-http","chapterTitle":"Errors — HTTP Codes","heading":"Case 2 — Expired or invalid Bearer token","snippet":"**Action:** Proactive refresh or redirect to login.","anchor":"case-2-expired-or-invalid-bearer-token"},{"id":"v1.0-dev-15-errors-http-5","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"15-errors-http","chapterTitle":"Errors — HTTP Codes","heading":"Case 3 — Invalid API Key","snippet":"```json\n{\n \"statusCode\": 401,\n \"message\": \"Cle API invalide\",\n \"error\": \"Unauthorized\"\n}\n```\n\n> The exact message varies depending on the cause (missing, invalid, or expired key — see [Business err","anchor":"case-3-invalid-api-key"},{"id":"v1.0-dev-15-errors-http-6","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"15-errors-http","chapterTitle":"Errors — HTTP Codes","heading":"402 — Payment Required","snippet":"Insufficient credits for an operation that consumes credits.\n\n```json\n{\n \"statusCode\": 402,\n \"message\": \"Insufficient credits\",\n \"error\": \"Payment Required\"\n}\n```\n\n**Action:** Redirect to the credi","anchor":"402-payment-required"},{"id":"v1.0-dev-15-errors-http-7","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"15-errors-http","chapterTitle":"Errors — HTTP Codes","heading":"403 — Forbidden","snippet":"The user is authenticated but lacks the necessary rights.","anchor":"403-forbidden"},{"id":"v1.0-dev-15-errors-http-8","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"15-errors-http","chapterTitle":"Errors — HTTP Codes","heading":"Case 1 — Insufficient admin level","snippet":"```json\n{\n \"statusCode\": 403,\n \"message\": \"Niveau d'administration insuffisant. Requis: CustomerAdmin, Actuel: User\",\n \"error\": \"Forbidden\"\n}\n```","anchor":"case-1-insufficient-admin-level"},{"id":"v1.0-dev-15-errors-http-9","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"15-errors-http","chapterTitle":"Errors — HTTP Codes","heading":"Case 2 — Missing application right","snippet":"```json\n{\n \"statusCode\": 403,\n \"message\": \"Droit requis : users.create\",\n \"error\": \"Forbidden\"\n}\n```","anchor":"case-2-missing-application-right"},{"id":"v1.0-dev-15-errors-http-10","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"15-errors-http","chapterTitle":"Errors — HTTP Codes","heading":"Case 3 — Feature disabled","snippet":"```json\n{\n \"statusCode\": 403,\n \"message\": \"La fonctionnalité invitation n'est pas activée pour ce customer\",\n \"error\": \"Forbidden\"\n}\n```\n\n**Action:** Display a clear message to the user. Do not ret","anchor":"case-3-feature-disabled"},{"id":"v1.0-dev-15-errors-http-11","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"15-errors-http","chapterTitle":"Errors — HTTP Codes","heading":"404 — Not Found","snippet":"The requested identifier (WID or UUID) does not exist in the database.\n\n> **A multi-tenant scope violation returns 403, not 404.** A `CustomerAdmin` (or any scoped token) attempting to access a Team, ","anchor":"404-not-found"},{"id":"v1.0-dev-15-errors-http-12","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"15-errors-http","chapterTitle":"Errors — HTTP Codes","heading":"409 — Conflict","snippet":"A uniqueness constraint is violated.\n\n**Common cases:**\n- Email already used within the Customer\n- `PENDING` invitation already exists for this email + Customer\n- Subdomain already used by another Net","anchor":"409-conflict"},{"id":"v1.0-dev-15-errors-http-13","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"15-errors-http","chapterTitle":"Errors — HTTP Codes","heading":"429 — Too Many Requests","snippet":"Rate limit exceeded.\n\n**Headers:** `Retry-After: 2` (duration in seconds before you can retry)\n\n**Action:** Respect the `Retry-After` header and implement an exponential backoff.\n\n```typescript\nconst ","anchor":"429-too-many-requests"},{"id":"v1.0-dev-15-errors-http-14","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"15-errors-http","chapterTitle":"Errors — HTTP Codes","heading":"5xx — Server errors","snippet":"**Possible causes:**\n- Unreachable downstream service (Keycloak, the WakaStart configuration service, the WakaStart authentication service)\n- Prisma error (unexpected DB constraint)\n- Internal timeout","anchor":"5xx-server-errors"},{"id":"v1.0-dev-15-errors-http-15","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"15-errors-http","chapterTitle":"Errors — HTTP Codes","heading":"Recommended frontend error handling","snippet":"```typescript\nclass ApiError extends Error {\n constructor(\n public readonly status: number,\n public readonly body: { statusCode: number; message: string | string[]; error: string }\n ) {\n su","anchor":"recommended-frontend-error-handling"},{"id":"v1.0-dev-15-errors-http-16","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"15-errors-http","chapterTitle":"Errors — HTTP Codes","heading":"Go further","snippet":"- [Business errors](16-errors-business): custom business codes, exact messages\n- [Common pitfalls](17-pitfalls): diagnosing frequent errors\n- [Rate limits](11-api-headers-rate-limits): limits per endp","anchor":"go-further"},{"id":"v1.0-dev-16-errors-business-0","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"16-errors-business","chapterTitle":"Errors — Business Codes","heading":"Strict messages (testable programmatically)","snippet":"Some `message` values have an exact, stable value:\n\n| Message | Status | Meaning |\n|---------|--------|---------------|\n| `\"Token enrichi manquant ou invalide\"` | 401 | wakaToken missing or invalid |\n","anchor":"strict-messages-testable-programmatically"},{"id":"v1.0-dev-16-errors-business-1","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"16-errors-business","chapterTitle":"Errors — Business Codes","heading":"Invitation errors — exhaustive handling","snippet":"```typescript\n// Handle the 4 error states of an invitation\nasync function loadInvitation(token: string) {\n const res = await fetch(`/api/proxy/invitations/verify/${token}`);\n const { valid, invitat","anchor":"invitation-errors-exhaustive-handling"},{"id":"v1.0-dev-16-errors-business-2","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"16-errors-business","chapterTitle":"Errors — Business Codes","heading":"Rights errors — structured messages","snippet":"`403` errors related to rights contain structured information in `message`:\n\n```typescript\n// Extract the required vs actual level from a 403\nfunction parseAdminLevelError(message: string) {\n const m","anchor":"rights-errors-structured-messages"},{"id":"v1.0-dev-16-errors-business-3","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"16-errors-business","chapterTitle":"Errors — Business Codes","heading":"Rate limit codes by endpoint","snippet":"Some endpoints have specific rate limit messages that let you identify the endpoint concerned:\n\n```typescript\n// Rate limit detection pattern\nfunction isRateLimitError(status: number, headers: Headers","anchor":"rate-limit-codes-by-endpoint"},{"id":"v1.0-dev-16-errors-business-4","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"16-errors-business","chapterTitle":"Errors — Business Codes","heading":"Validation errors — parsing","snippet":"For `400`s with an array of messages, build a map of fields in error:\n\n```typescript\ninterface ValidationErrors {\n [field: string]: string[];\n}\n\nfunction parseValidationErrors(\n messages: string | s","anchor":"validation-errors-parsing"},{"id":"v1.0-dev-16-errors-business-5","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"16-errors-business","chapterTitle":"Errors — Business Codes","heading":"Conflict errors (409) — strategies","snippet":"```typescript\ntry {\n await createInvitation(dto);\n toast.success(\"Invitation envoyée\");\n} catch (err) {\n if (err instanceof ApiError && err.isConflict) {\n const msg = err.body.message as string;","anchor":"conflict-errors-409-strategies"},{"id":"v1.0-dev-16-errors-business-6","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"16-errors-business","chapterTitle":"Errors — Business Codes","heading":"Go further","snippet":"- [HTTP errors](15-errors-http): full 400-5xx codes\n- [Invitations — Verification](19-invitations-verify-accept): handling `valid: false`\n- [Common pitfalls](17-pitfalls): diagnosing recurring errors","anchor":"go-further"},{"id":"v1.0-dev-18-invitations-create-0","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"18-invitations-create","chapterTitle":"Invitations API — Creation","heading":"Prerequisites","snippet":"1. **`invitation` feature enabled** in cascade (App ∧ Network ∧ Customer)\n2. **`invitations.create` right** on the token or API key — this right is an `AppRight` granted via the profile(s) assigned to","anchor":"prerequisites"},{"id":"v1.0-dev-18-invitations-create-1","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"18-invitations-create","chapterTitle":"Invitations API — Creation","heading":"Invitation lifecycle","snippet":"```mermaid\nstateDiagram-v2\n [*] --> PENDING : creation\n PENDING --> ACCEPTED : acceptance\n PENDING --> EXPIRED : expiration (10 days)\n PENDING --> CANCELLED : revocation\n ACCEPTED --> [*]\n EXPIR","anchor":"invitation-lifecycle"},{"id":"v1.0-dev-18-invitations-create-2","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"18-invitations-create","chapterTitle":"Invitations API — Creation","heading":"Full invitation flow","snippet":"```mermaid\nsequenceDiagram\n participant App as Your WakaApp\n participant WS as WakaStart\n participant Invitee as Invitee\n\n App->>WS: POST /api/invitations\n WS-->>App: 201 { id, token, ... }\n WS-","anchor":"full-invitation-flow"},{"id":"v1.0-dev-18-invitations-create-3","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"18-invitations-create","chapterTitle":"Invitations API — Creation","heading":"Endpoint — Create an invitation","snippet":"```http\nPOST /api/invitations\nAuthorization: Bearer \nContent-Type: application/json\n\n{\n \"customerId\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"invitedEmail\": \"alice@acme.com\",\n \"invited","anchor":"endpoint-create-an-invitation"},{"id":"v1.0-dev-18-invitations-create-4","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"18-invitations-create","chapterTitle":"Invitations API — Creation","heading":"Management endpoints","snippet":"","anchor":"management-endpoints"},{"id":"v1.0-dev-18-invitations-create-5","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"18-invitations-create","chapterTitle":"Invitations API — Creation","heading":"List invitations","snippet":"```http\nGET /api/invitations/sent # By the current user\nGET /api/invitations/sent/app/:appId # Filtered by App\nGET /api/invitations/by-customer/:customerId ","anchor":"list-invitations"},{"id":"v1.0-dev-18-invitations-create-6","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"18-invitations-create","chapterTitle":"Invitations API — Creation","heading":"Resend an invitation","snippet":"```http\nPOST /api/invitations/:id/resend\n```\n\nGenerates a new token, resets `expiresAt` to +10 days, resends the email. The old token is immediately invalidated.\n\nUsable on `PENDING` or `EXPIRED` invi","anchor":"resend-an-invitation"},{"id":"v1.0-dev-18-invitations-create-7","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"18-invitations-create","chapterTitle":"Invitations API — Creation","heading":"Revoke an invitation","snippet":"```http\nDELETE /api/invitations/:id\n```\n\nSets the invitation to `CANCELLED`. Response `200 OK`. Required right: `invitations.revoke`.\n\n---","anchor":"revoke-an-invitation"},{"id":"v1.0-dev-18-invitations-create-8","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"18-invitations-create","chapterTitle":"Invitations API — Creation","heading":"curl example","snippet":"```bash\n# Create the invitation from your backend\ncurl -X POST https://api.wakastart.app/api/invitations \\\n -H \"x-api-key: sk_live_yourkey\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"cust","anchor":"curl-example"},{"id":"v1.0-dev-18-invitations-create-9","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"18-invitations-create","chapterTitle":"Invitations API — Creation","heading":"Best practices","snippet":"- **Idempotency on creation:** if a call fails after creation (network issue), retrying will raise a `409 Conflict` — this is safe, the existing invitation is still valid.\n- **Never log the invitation","anchor":"best-practices"},{"id":"v1.0-dev-18-invitations-create-10","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"18-invitations-create","chapterTitle":"Invitations API — Creation","heading":"Go further","snippet":"- [Invitations — Verification & Acceptance](19-invitations-verify-accept): `verify`, `accept`, full lifecycle\n- [Feature flags](09-access-control-features): enabling the `invitations` feature\n- [Busin","anchor":"go-further"},{"id":"v1.0-dev-19-invitations-verify-accept-0","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"19-invitations-verify-accept","chapterTitle":"Invitations API — Verification & Acceptance","heading":"Endpoint — Verify a token (PUBLIC)","snippet":"To be called from your acceptance page on load, before displaying the form.\n\n```http\nGET /api/invitations/verify/{token}\n```\n\n**Auth:** None — public endpoint. **Throttle:** 10 req/min/IP.\n\n**Valid re","anchor":"endpoint-verify-a-token-public"},{"id":"v1.0-dev-19-invitations-verify-accept-1","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"19-invitations-verify-accept","chapterTitle":"Invitations API — Verification & Acceptance","heading":"React pattern — Acceptance page","snippet":"```typescript\n// app/accept-invitation/[token]/page.tsx\nasync function AcceptInvitationPage({ params }: { params: { token: string } }) {\n // Call the public-api DIRECTLY: the BFF controller (/api/pro","anchor":"react-pattern-acceptance-page"},{"id":"v1.0-dev-19-invitations-verify-accept-2","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"19-invitations-verify-accept","chapterTitle":"Invitations API — Verification & Acceptance","heading":"Endpoint — Accept an invitation (PUBLIC)","snippet":"```http\nPOST /api/invitations/accept/{token}\nContent-Type: application/json\n\n{ \"password\": \"MotDePasse2026!\" }\n```\n\n**Auth:** None — public endpoint. **Throttle:** 5 req/min/IP.\n\n**201 Response:**\n\n``","anchor":"endpoint-accept-an-invitation-public"},{"id":"v1.0-dev-19-invitations-verify-accept-3","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"19-invitations-verify-accept","chapterTitle":"Invitations API — Verification & Acceptance","heading":"curl example — full flow","snippet":"```bash\n# 1. Your backend creates the invitation\ncurl -X POST https://api.wakastart.app/api/invitations \\\n -H \"x-api-key: sk_live_yourkey\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"custo","anchor":"curl-example-full-flow"},{"id":"v1.0-dev-19-invitations-verify-accept-4","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"19-invitations-verify-accept","chapterTitle":"Invitations API — Verification & Acceptance","heading":"Best practices","snippet":"- **Always call `verify` on mount** before displaying the form — this saves the invitee from filling in a password for nothing.\n- **Handle the 4 error states** with explicit, appropriate messages.","anchor":"best-practices"},{"id":"v1.0-dev-19-invitations-verify-accept-5","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"19-invitations-verify-accept","chapterTitle":"Invitations API — Verification & Acceptance","heading":"Common pitfalls","snippet":"- **Calling `accept` twice**: after acceptance, the token is invalidated. The second call returns `400 Cette invitation a déjà été acceptée`.\n- **Forgetting the initial `verify`**: the invitee fills i","anchor":"common-pitfalls"},{"id":"v1.0-dev-19-invitations-verify-accept-6","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"19-invitations-verify-accept","chapterTitle":"Invitations API — Verification & Acceptance","heading":"Go further","snippet":"- [Invitations — Creation](18-invitations-create): POST endpoint, prerequisites, lifecycle\n- [Business errors](16-errors-business): handling `valid: false` messages\n- [Access control](07-access-contro","anchor":"go-further"},{"id":"v1.0-dev-20-mcp-server-overview-0","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"20-mcp-server-overview","chapterTitle":"MCP Server — Overview","heading":"Why this integration","snippet":"Rather than juggling between this documentation and your IDE, you can configure Claude Code to query the MCP directly and get: the list of available endpoints, full DTO details, generated curl example","anchor":"why-this-integration"},{"id":"v1.0-dev-20-mcp-server-overview-1","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"20-mcp-server-overview","chapterTitle":"MCP Server — Overview","heading":"5 available tools","snippet":"","anchor":"5-available-tools"},{"id":"v1.0-dev-20-mcp-server-overview-2","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"20-mcp-server-overview","chapterTitle":"MCP Server — Overview","heading":"1. `list_endpoints`","snippet":"Lists all `/api/*` endpoints with HTTP method, route, required right, and description.\n\n```bash\ncurl -X POST https://docs.wakastart.app/api/mcp \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"j","anchor":"1-list_endpoints"},{"id":"v1.0-dev-20-mcp-server-overview-3","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"20-mcp-server-overview","chapterTitle":"MCP Server — Overview","heading":"2. `get_endpoint_spec`","snippet":"Full detail of an endpoint: request/response DTO, HTTP codes, required right, examples.\n\n```bash\ncurl -X POST https://docs.wakastart.app/api/mcp \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"","anchor":"2-get_endpoint_spec"},{"id":"v1.0-dev-20-mcp-server-overview-4","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"20-mcp-server-overview","chapterTitle":"MCP Server — Overview","heading":"3. `search_docs`","snippet":"Full-text search across the site's Markdown documentation chapters.\n\n```bash\ncurl -X POST https://docs.wakastart.app/api/mcp \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"jsonrpc\": \"2.0\",\n ","anchor":"3-search_docs"},{"id":"v1.0-dev-20-mcp-server-overview-5","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"20-mcp-server-overview","chapterTitle":"MCP Server — Overview","heading":"4. `get_auth_flow`","snippet":"Structured summary of the authentication flow.\n\n**Parameters:**\n- `format`: `summary` | `full` (default: `full`)\n- `context`: `frontend` | `backend` | `mobile`\n\n---","anchor":"4-get_auth_flow"},{"id":"v1.0-dev-20-mcp-server-overview-6","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"20-mcp-server-overview","chapterTitle":"MCP Server — Overview","heading":"5. `get_error_code`","snippet":"Detail of a Wakastart HTTP or business error code.\n\n**Recognized codes:** `401`, `403`, `404`, `409`, `429`, `5xx`, `BOLA`, `TOKEN_EXPIRED`, `VULN-002`…\n\n---","anchor":"5-get_error_code"},{"id":"v1.0-dev-20-mcp-server-overview-7","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"20-mcp-server-overview","chapterTitle":"MCP Server — Overview","heading":"Available resources","snippet":"```bash\n# MCP handshake (required before any interaction)\ncurl -X POST https://docs.wakastart.app/api/mcp \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"jsonrpc\": \"2.0\",\n \"id\": 0,\n \"meth","anchor":"available-resources"},{"id":"v1.0-dev-20-mcp-server-overview-8","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"20-mcp-server-overview","chapterTitle":"MCP Server — Overview","heading":"Technical characteristics","snippet":"| Aspect | Value |\n|--------|--------|\n| **Transport** | HTTP (JSON-RPC 2.0) |\n| **Authentication** | None (public documentation) |\n| **Rate limit** | No rate limiting currently |\n| **Mutations** | No","anchor":"technical-characteristics"},{"id":"v1.0-dev-20-mcp-server-overview-9","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"20-mcp-server-overview","chapterTitle":"MCP Server — Overview","heading":"URLs per environment","snippet":"| Environment | MCP URL |\n|---------------|---------|\n| Local dev | `http://localhost/api/mcp` |\n| Staging | `https://docs-staging.wakastart.app/api/mcp` |\n| Production | `https://docs.wakastart.app/a","anchor":"urls-per-environment"},{"id":"v1.0-dev-20-mcp-server-overview-10","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"20-mcp-server-overview","chapterTitle":"MCP Server — Overview","heading":"Swagger UI","snippet":"The OpenAPI spec is also available via this site's interactive interface:\n\n```\nhttps://docs.wakastart.app/v1.0/dev/api-reference\n```\n\n**Raw JSON (for import into Postman, Insomnia, etc.):**\nIf your lo","anchor":"swagger-ui"},{"id":"v1.0-dev-20-mcp-server-overview-11","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"20-mcp-server-overview","chapterTitle":"MCP Server — Overview","heading":"Best practices","snippet":"- Use `list_endpoints` + `get_endpoint_spec` at the start of a sprint to discover new routes.\n- The MCP is read-only — it cannot modify the platform.\n- In CI/CD, do not include `.mcp.json` in the prod","anchor":"best-practices"},{"id":"v1.0-dev-20-mcp-server-overview-12","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"20-mcp-server-overview","chapterTitle":"MCP Server — Overview","heading":"Go further","snippet":"- [Claude Code Configuration](21-mcp-server-claude-code-setup): `.mcp.json`, examples and advanced usage\n- [Endpoint reference](14-endpoint-reference): static table of all routes","anchor":"go-further"},{"id":"v1.0-dev-21-mcp-server-claude-code-setup-0","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"21-mcp-server-claude-code-setup","chapterTitle":"MCP Server — Claude Code Configuration","heading":"`.mcp.json` configuration","snippet":"Create a `.mcp.json` file at the root of your WakaApp project:\n\n```json\n{\n \"mcpServers\": {\n \"wakastart-docs\": {\n \"url\": \"http://localhost/api/mcp\",\n \"transport\": \"http\"\n }\n }\n}\n```\n\n","anchor":"mcpjson-configuration"},{"id":"v1.0-dev-21-mcp-server-claude-code-setup-1","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"21-mcp-server-claude-code-setup","chapterTitle":"MCP Server — Claude Code Configuration","heading":"Questions you can ask Claude","snippet":"Once configured, query directly from Claude Code:","anchor":"questions-you-can-ask-claude"},{"id":"v1.0-dev-21-mcp-server-claude-code-setup-2","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"21-mcp-server-claude-code-setup","chapterTitle":"MCP Server — Claude Code Configuration","heading":"Via `list_endpoints`","snippet":"- *\"Show me all authentication endpoints\"*\n- *\"Which endpoints accept POST?\"*\n- *\"List all invitation endpoints with their required rights\"*","anchor":"via-list_endpoints"},{"id":"v1.0-dev-21-mcp-server-claude-code-setup-3","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"21-mcp-server-claude-code-setup","chapterTitle":"MCP Server — Claude Code Configuration","heading":"Via `get_endpoint_spec`","snippet":"- *\"What body is expected for POST /api/invitations?\"*\n- *\"What error codes can DELETE /api/invitations/:id return?\"*\n- *\"Generate a curl example for POST /api/auth/enrich\"*","anchor":"via-get_endpoint_spec"},{"id":"v1.0-dev-21-mcp-server-claude-code-setup-4","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"21-mcp-server-claude-code-setup","chapterTitle":"MCP Server — Claude Code Configuration","heading":"Via `search_docs`","snippet":"- *\"How does PKCE work in Wakastart?\"*\n- *\"What is an AppRight?\"*\n- *\"How do I configure rate limiting on the Wakapp side?\"*","anchor":"via-search_docs"},{"id":"v1.0-dev-21-mcp-server-claude-code-setup-5","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"21-mcp-server-claude-code-setup","chapterTitle":"MCP Server — Claude Code Configuration","heading":"Via `get_auth_flow`","snippet":"- *\"Explain the Wakastart auth flow for a frontend app\"*\n- *\"How does M2M auth work with an API key?\"*","anchor":"via-get_auth_flow"},{"id":"v1.0-dev-21-mcp-server-claude-code-setup-6","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"21-mcp-server-claude-code-setup","chapterTitle":"MCP Server — Claude Code Configuration","heading":"Via `get_error_code`","snippet":"- *\"Why am I getting a 401?\"*\n- *\"What is BOLA?\"*\n- *\"When does the API return a 409?\"*\n\n---","anchor":"via-get_error_code"},{"id":"v1.0-dev-21-mcp-server-claude-code-setup-7","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"21-mcp-server-claude-code-setup","chapterTitle":"MCP Server — Claude Code Configuration","heading":"Verifying the server","snippet":"Test that the server responds:\n\n```bash\n# Handshake\ncurl -X POST http://localhost/api/mcp \\\n -H \"Content-Type: application/json\" \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":0,\"method\":\"initialize\",\"params\":{\"proto","anchor":"verifying-the-server"},{"id":"v1.0-dev-21-mcp-server-claude-code-setup-8","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"21-mcp-server-claude-code-setup","chapterTitle":"MCP Server — Claude Code Configuration","heading":"Example Claude Code session","snippet":"Once `.mcp.json` is configured:\n\n```\nYou: \"Generate the TypeScript code to call POST /api/invitations\"\n\nClaude: [Calls list_endpoints with tag=\"Invitations\"]\n [Calls get_endpoint_spec with path","anchor":"example-claude-code-session"},{"id":"v1.0-dev-21-mcp-server-claude-code-setup-9","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"21-mcp-server-claude-code-setup","chapterTitle":"MCP Server — Claude Code Configuration","heading":"Using `resources/read`","snippet":"To read a full documentation chapter in Claude:\n\n```bash\ncurl -X POST https://docs.wakastart.app/api/mcp \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"jsonrpc\": \"2.0\",\n \"id\": 6,\n \"metho","anchor":"using-resourcesread"},{"id":"v1.0-dev-21-mcp-server-claude-code-setup-10","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"21-mcp-server-claude-code-setup","chapterTitle":"MCP Server — Claude Code Configuration","heading":"Best practices","snippet":"- Use `list_endpoints` + `get_endpoint_spec` at the start of a sprint.\n- The MCP is read-only — no risk of modifying the platform.\n- In CI/CD, **do not include `.mcp.json`** in the production containe","anchor":"best-practices"},{"id":"v1.0-dev-21-mcp-server-claude-code-setup-11","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"21-mcp-server-claude-code-setup","chapterTitle":"MCP Server — Claude Code Configuration","heading":"Go further","snippet":"- [MCP Overview](20-mcp-server-overview): tools, resources, technical characteristics\n- [Endpoint reference](14-endpoint-reference): static table of all routes","anchor":"go-further"},{"id":"v1.0-dev-22-platform-overview-0","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"22-platform-overview","chapterTitle":"Platform Overview","heading":"📍 Where to access the Infra section in the UI","snippet":"**Applications** menu → click on your app → the **🚀 green rocket** icon on the app card opens the **Infra / Hosting** area dedicated to that app.\n\nThis is the entry point for all hosting features: ar","anchor":"-where-to-access-the-infra-section-in-the-ui"},{"id":"v1.0-dev-22-platform-overview-1","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"22-platform-overview","chapterTitle":"Platform Overview","heading":"The mantra to remember","snippet":"> *You declare **what** your app contains.*\n> *Wakastart **builds**, **hosts**, and **runs** it.*","anchor":"the-mantra-to-remember"},{"id":"v1.0-dev-23-app-hierarchy-0","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"23-app-hierarchy","chapterTitle":"App → Environment → Instances Hierarchy","heading":"Why this separation between Architecture and Environment?","snippet":"The **Architecture** describes your app **once**: \"I have a Node.js backend, a PostgreSQL database, an S3 bucket\".\n\n**Environments** instantiate this architecture **as many times as you want**: dev, s","anchor":"why-this-separation-between-architecture-and-environment"},{"id":"v1.0-dev-36-architecture-json-0","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"36-architecture-json","chapterTitle":"Describing your architecture in JSON","heading":"Why use it?","snippet":"- **Get started fast.** No more clicking 30 times to create 5 services, 1 database, and 2 URLs: a single JSON file and it's imported.\n- **Clone an app.** Export an app that works, import it into anoth","anchor":"why-use-it"},{"id":"v1.0-dev-36-architecture-json-1","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"36-architecture-json","chapterTitle":"Describing your architecture in JSON","heading":"In short","snippet":"The JSON describes **only your architecture**: repos, services, databases, storage, URLs, environments. Not your secrets, not your credentials, not your data volumes.\n\nOnce imported, your app has the ","anchor":"in-short"},{"id":"v1.0-dev-36-architecture-json-2","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"36-architecture-json","chapterTitle":"Describing your architecture in JSON","heading":"Importing an architecture","snippet":"","anchor":"importing-an-architecture"},{"id":"v1.0-dev-36-architecture-json-3","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"36-architecture-json","chapterTitle":"Describing your architecture in JSON","heading":"Prerequisites","snippet":"- You have **created the target app** (however you like).\n- The target app is **blank on the architecture side**: no service, no database, no bucket, no URL has been manually added yet.\n\n> If the app ","anchor":"prerequisites"},{"id":"v1.0-dev-36-architecture-json-4","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"36-architecture-json","chapterTitle":"Describing your architecture in JSON","heading":"Procedure","snippet":"1. Open your app → **Architecture**\n2. Click **Import** (top right, next to **Export**)\n3. **Step 1 — Paste + Validate**\n - Paste your JSON into the text field\n - Click **Validate**: if the JSON c","anchor":"procedure"},{"id":"v1.0-dev-36-architecture-json-5","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"36-architecture-json","chapterTitle":"Describing your architecture in JSON","heading":"Exporting an architecture","snippet":"","anchor":"exporting-an-architecture"},{"id":"v1.0-dev-36-architecture-json-6","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"36-architecture-json","chapterTitle":"Describing your architecture in JSON","heading":"When?","snippet":"- You have an app that works well and want to **clone** it to another target app (different WakaStart, different environment).\n- You want to **archive** your app's infra description to version it in y","anchor":"when"},{"id":"v1.0-dev-36-architecture-json-7","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"36-architecture-json","chapterTitle":"Describing your architecture in JSON","heading":"Procedure","snippet":"1. Open your app → **Architecture**\n2. Click **Export** → a dialog opens with a summary of the transformations applied\n3. Choose either:\n - **Copy** the JSON to the clipboard\n - **Download** the `","anchor":"procedure"},{"id":"v1.0-dev-36-architecture-json-8","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"36-architecture-json","chapterTitle":"Describing your architecture in JSON","heading":"What is exported and what isn't","snippet":"| Included | Excluded |\n|---|---|\n| App metadata (`name`, `shortname`) | Technical identifiers (regenerated on the target app) |\n| Repos (read-only) | Git credentials |\n| Services + expected env varia","anchor":"what-is-exported-and-what-isnt"},{"id":"v1.0-dev-36-architecture-json-9","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"36-architecture-json","chapterTitle":"Describing your architecture in JSON","heading":"The JSON format — practical reference","snippet":"","anchor":"the-json-format-practical-reference"},{"id":"v1.0-dev-36-architecture-json-10","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"36-architecture-json","chapterTitle":"Describing your architecture in JSON","heading":"Minimal skeleton","snippet":"```json\n{\n \"version\": \"1.0\",\n \"kind\": \"wakastart-app-architecture\",\n \"app\": {\n \"name\": \"Mon Application\",\n \"shortname\": \"monapp\"\n }\n}\n```\n\nThe `app` block and the `version` + `kind` header a","anchor":"minimal-skeleton"},{"id":"v1.0-dev-36-architecture-json-11","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"36-architecture-json","chapterTitle":"Describing your architecture in JSON","heading":"Available sections","snippet":"| Section | Type | When to use it |\n|---|---|---|\n| `app` | required | Metadata (name, shortname) |\n| `repos` | recommended | Your GitHub repos to connect |\n| `serviceDefinitions` | recommended | Your","anchor":"available-sections"},{"id":"v1.0-dev-36-architecture-json-12","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"36-architecture-json","chapterTitle":"Describing your architecture in JSON","heading":"The `repos` block","snippet":"Your GitHub repos to connect to your app. **Two modes** to choose from depending on whether the repo already exists or not:\n\n#### Mode 1 — managed repo (`isManaged: true`): WakaStart creates it for yo","anchor":"the-repos-block"},{"id":"v1.0-dev-36-architecture-json-13","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"36-architecture-json","chapterTitle":"Describing your architecture in JSON","heading":"The `serviceDefinitions` block","snippet":"```json\n\"serviceDefinitions\": [\n {\n \"ref\": \"api\",\n \"name\": \"API Backend\",\n \"shortname\": \"api\",\n \"repoRef\": \"main-repo\",\n \"rootDirectory\": \"./backend\",\n \"dockerfilePath\": \"Dockerfile","anchor":"the-servicedefinitions-block"},{"id":"v1.0-dev-36-architecture-json-14","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"36-architecture-json","chapterTitle":"Describing your architecture in JSON","heading":"The `databaseDefinitions` block","snippet":"```json\n\"databaseDefinitions\": [\n {\n \"ref\": \"pg\",\n \"name\": \"PostgreSQL principale\",\n \"shortname\": \"pg\",\n \"engineType\": \"POSTGRESQL\",\n \"defaultMode\": \"IN_CLUSTER\",\n \"defaultPlan\": \"e","anchor":"the-databasedefinitions-block"},{"id":"v1.0-dev-36-architecture-json-15","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"36-architecture-json","chapterTitle":"Describing your architecture in JSON","heading":"The `storageBucketDefinitions` block","snippet":"```json\n\"storageBucketDefinitions\": [\n {\n \"ref\": \"uploads\",\n \"name\": \"Uploads utilisateurs\",\n \"shortname\": \"uploads\",\n \"defaultRegion\": \"gra\",\n \"defaultStorageClass\": \"STANDARD\",\n \"","anchor":"the-storagebucketdefinitions-block"},{"id":"v1.0-dev-36-architecture-json-16","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"36-architecture-json","chapterTitle":"Describing your architecture in JSON","heading":"The `appUrls` and `appRoutes` blocks","snippet":"```json\n\"appUrls\": [\n { \"ref\": \"api-url\", \"subdomain\": \"api\", \"domainRef\": null },\n { \"ref\": \"app-url\", \"subdomain\": \"app\", \"domainRef\": null }\n],\n\"appRoutes\": [\n { \"serviceRef\": \"api\", \"urlRef\":","anchor":"the-appurls-and-approutes-blocks"},{"id":"v1.0-dev-36-architecture-json-17","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"36-architecture-json","chapterTitle":"Describing your architecture in JSON","heading":"The `appApexUrls` and `appUrlRedirects` blocks (`CUSTOM` domains only)","snippet":"These two blocks describe capabilities tied to a **`CUSTOM` domain**: exposing the app at the root of a domain (apex) and redirecting one URL to another within the app (see [URLs and routing](./routin","anchor":"the-appapexurls-and-appurlredirects-blocks-custom-domains-only"},{"id":"v1.0-dev-36-architecture-json-18","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"36-architecture-json","chapterTitle":"Describing your architecture in JSON","heading":"The `environments` block (optional)","snippet":"```json\n\"environments\": [\n { \"env\": \"dev\", \"shortname\": \"dev\", \"slug\": \"dev\", \"urlPrefix\": \"dev\" },\n { \"env\": \"staging\", \"shortname\": \"stg\", \"slug\": \"staging\", \"urlPrefix\": \"staging\" },\n { ","anchor":"the-environments-block-optional"},{"id":"v1.0-dev-36-architecture-json-19","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"36-architecture-json","chapterTitle":"Describing your architecture in JSON","heading":"Three concrete examples","snippet":"","anchor":"three-concrete-examples"},{"id":"v1.0-dev-36-architecture-json-20","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"36-architecture-json","chapterTitle":"Describing your architecture in JSON","heading":"1. Monolithic app (back + front)","snippet":"```json\n{\n \"version\": \"1.0\",\n \"kind\": \"wakastart-app-architecture\",\n \"app\": { \"name\": \"Hello World\", \"shortname\": \"hello\" },\n \"repos\": [\n {\n \"ref\": \"main\",\n \"name\": \"hello-world\",\n ","anchor":"1-monolithic-app-back-front"},{"id":"v1.0-dev-36-architecture-json-21","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"36-architecture-json","chapterTitle":"Describing your architecture in JSON","heading":"2. App with a database and storage","snippet":"Add the `databaseDefinitions` + `storageBucketDefinitions` blocks to the previous one, and declare the variables your backend expects:\n\n```json\n\"databaseDefinitions\": [\n {\n \"ref\": \"pg\", \"name\": \"P","anchor":"2-app-with-a-database-and-storage"},{"id":"v1.0-dev-36-architecture-json-22","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"36-architecture-json","chapterTitle":"Describing your architecture in JSON","heading":"3. Multi-service app with preconfigured environments","snippet":"If you want to create the environments in a single import:\n\n```json\n\"environments\": [\n { \"env\": \"dev\", \"shortname\": \"dev\", \"slug\": \"dev\", \"urlPrefix\": \"dev\" },\n { \"env\": \"prod\", \"shortname\": \"prd\"","anchor":"3-multi-service-app-with-preconfigured-environments"},{"id":"v1.0-dev-36-architecture-json-23","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"36-architecture-json","chapterTitle":"Describing your architecture in JSON","heading":"Best practices","snippet":"- **One `shortname` per block**: a service `api` and a database `api` can coexist, but two services with `shortname: \"api\"` cannot.\n- **Consistency of `varRequirements`**: declare **all** the variable","anchor":"best-practices"},{"id":"v1.0-dev-36-architecture-json-24","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"36-architecture-json","chapterTitle":"Describing your architecture in JSON","heading":"Common errors","snippet":"| Symptom | Cause | Fix |\n|---|---|---|\n| **Import** button greyed out | The target app already contains resources | Create a **blank app** (never edited) or delete the resources |\n| Step 1 shows `ser","anchor":"common-errors"},{"id":"v1.0-dev-36-architecture-json-25","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"36-architecture-json","chapterTitle":"Describing your architecture in JSON","heading":"Using an AI to generate the JSON","snippet":"The format is deliberately **predictable** and **strict** so that an assistant like Claude, ChatGPT, Cursor, etc. produces valid JSON on the first try.","anchor":"using-an-ai-to-generate-the-json"},{"id":"v1.0-dev-36-architecture-json-26","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"36-architecture-json","chapterTitle":"Describing your architecture in JSON","heading":"Sample prompt","snippet":"> Here's the description of my project: I want a Node.js API that connects to a PostgreSQL database and writes files to an S3 bucket, plus a Next.js frontend. I want WakaStart to create a new repo for","anchor":"sample-prompt"},{"id":"v1.0-dev-36-architecture-json-27","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"36-architecture-json","chapterTitle":"Describing your architecture in JSON","heading":"Tips","snippet":"- Ask the AI to **validate the JSON** before handing it to you (header keys `\"version\": \"1.0\"`, `\"kind\": \"wakastart-app-architecture\"`).\n- If the **Validate** step shows errors, **feed them back** to ","anchor":"tips"},{"id":"v1.0-dev-36-architecture-json-28","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"36-architecture-json","chapterTitle":"Describing your architecture in JSON","heading":"Going further","snippet":"- [Repositories](./repositories)\n- [Services](./services)\n- [Databases, storage, routing](./databases-storage)\n- [URLs and routing](./routing-urls)\n- [Variables and secrets](./vars-secrets)\n- [Environ","anchor":"going-further"},{"id":"v1.0-dev-24-repositories-0","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"24-repositories","chapterTitle":"Repository (Git repository)","heading":"What is a repo used for in Wakastart?","snippet":"A repo is **not** a service on its own. It provides the source code that will then be:\n\n1. Read to perform a **Build** (turn the code into a Docker image)\n2. Used for its branches/tags (Git reference ","anchor":"what-is-a-repo-used-for-in-wakastart"},{"id":"v1.0-dev-25-services-0","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"25-services","chapterTitle":"Service — executable component","heading":"ServiceDefinition (Architecture level)","snippet":"This is the generic **definition** of the service. You describe:\n\n| Field | Example | Explanation |\n|-------|---------|-------------|\n| **Role** | `BACK` | Backend, frontend, API, worker… |\n| **Protoc","anchor":"servicedefinition-architecture-level"},{"id":"v1.0-dev-25-services-1","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"25-services","chapterTitle":"Service — executable component","heading":"Configuring the build: rootDirectory, dockerfilePath, buildContext","snippet":"Three ServiceDefinition parameters drive the `docker build` step:\n\n| Field | Role | Relative to |\n|-------|------|-----------|\n| **rootDirectory** | Base directory used as a \"virtual root\" for this se","anchor":"configuring-the-build-rootdirectory-dockerfilepath-buildcontext"},{"id":"v1.0-dev-25-services-2","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"25-services","chapterTitle":"Service — executable component","heading":"Case 1 — Simple repo, Dockerfile at the root","snippet":"```\nle BFF WakaStart/\n├── Dockerfile\n├── package.json\n└── src/\n```\n\n| Field | Value |\n|-------|--------|\n| `rootDirectory` | `./` |\n| `dockerfilePath` | `Dockerfile` |\n| `buildContext` | `.` |\n\nEquiva","anchor":"case-1-simple-repo-dockerfile-at-the-root"},{"id":"v1.0-dev-25-services-3","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"25-services","chapterTitle":"Service — executable component","heading":"Case 2 — Monorepo, project in a subfolder","snippet":"```\nle BFF WakaStart/\n├── apps/\n│ ├── backend/\n│ │ ├── Dockerfile\n│ │ ├── package.json\n│ │ └── src/\n│ └── worker/\n└── packages/\n```\n\nYou want to build only `apps/backend` and restrict ","anchor":"case-2-monorepo-project-in-a-subfolder"},{"id":"v1.0-dev-25-services-4","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"25-services","chapterTitle":"Service — executable component","heading":"Case 3 — Monorepo with a shared lockfile (pnpm/yarn workspaces, turbo…)","snippet":"Your service is in `apps/backend/` but needs the root `pnpm-lock.yaml` and the shared `packages/*` packages to install:\n\n```\nle BFF WakaStart/\n├── pnpm-lock.yaml ← lockfile racine\n├── pnpm-wor","anchor":"case-3-monorepo-with-a-shared-lockfile-pnpmyarn-workspaces-turbo"},{"id":"v1.0-dev-25-services-5","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"25-services","chapterTitle":"Service — executable component","heading":"Practical rules","snippet":"- **The smaller the `buildContext`, the faster the build** (Docker sends fewer files to the daemon). If your service is self-contained in a subfolder, go with Case 2.\n- **If your Dockerfile needs file","anchor":"practical-rules"},{"id":"v1.0-dev-25-services-6","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"25-services","chapterTitle":"Service — executable component","heading":"ServiceInstance (Environment level)","snippet":"This is the actual **instance** of a service in a given environment (e.g. backend in dev, backend in prod). It inherits default values from the Definition but can override them:\n\n```\nServiceDefinition","anchor":"serviceinstance-environment-level"},{"id":"v1.0-dev-26-builds-0","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"26-builds","chapterTitle":"Build — from code to Docker image","heading":"The Build pipeline","snippet":"```\nRepository (code source)\n ↓\n git checkout \n ↓\n docker build (Dockerfile)\n ↓\n Image Docker dans le registry privé Wakastart\n ↓\n Disponible pour déploi","anchor":"the-build-pipeline"},{"id":"v1.0-dev-26-builds-1","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"26-builds","chapterTitle":"Build — from code to Docker image","heading":"Build statuses","snippet":"| Status | Meaning |\n|--------|---------------|\n| `PENDING` | Waiting to run |\n| `BUILDING` | Docker build in progress |\n| `PUSHING` | Image built, being uploaded to the registry |\n| `SUCCEEDED` | OK,","anchor":"build-statuses"},{"id":"v1.0-dev-26-builds-2","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"26-builds","chapterTitle":"Build — from code to Docker image","heading":"How to trigger a build","snippet":"| Trigger | When |\n|---------|------|\n| `MANUAL` | You click \"Build\" in the UI, choosing a branch/tag/commit |\n| `GIT_PUSH` | 🚧 *Coming soon* — will automatically trigger a build on push to the watch","anchor":"how-to-trigger-a-build"},{"id":"v1.0-dev-26-builds-3","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"26-builds","chapterTitle":"Build — from code to Docker image","heading":"Image names","snippet":"Each build produces an image with a unique name. Date and time are in UTC.\n\n| Build type | Image name | Example |\n|------------|------------|---------|\n| Branch | `-YYYYMMDD-hhmmss` | `main-20","anchor":"image-names"},{"id":"v1.0-dev-26-builds-4","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"26-builds","chapterTitle":"Build — from code to Docker image","heading":"Build cache","snippet":"Every build starts from scratch: the platform doesn't reuse any layer from a previous build. There is no \"No cache\" option anymore.\n\nThe API still accepts the `noCache` field, so existing calls don't ","anchor":"build-cache"},{"id":"v1.0-dev-26-builds-5","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"26-builds","chapterTitle":"Build — from code to Docker image","heading":"Image retention (automatic purge)","snippet":"Each successful build leaves an image in the app's registry. Without a purge, these images pile up. The automatic purge deletes the images of the oldest builds, while always keeping the ones still in ","anchor":"image-retention-automatic-purge"},{"id":"v1.0-dev-26-builds-6","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"26-builds","chapterTitle":"Build — from code to Docker image","heading":"Enabling the purge","snippet":"The purge is **disabled by default**. It's set app by app:\n\nThe purge card is only displayed in French: its labels are quoted as they appear on screen, followed by a translation.\n\n1. Open Infra → **Bu","anchor":"enabling-the-purge"},{"id":"v1.0-dev-26-builds-7","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"26-builds","chapterTitle":"Build — from code to Docker image","heading":"What is kept","snippet":"Builds are sorted into groups. In each group, the N most recent are kept (N = the number you chose):\n\n| Build type | Group |\n|------------|-------|\n| Branch | the branch |\n| Commit attached to a branc","anchor":"what-is-kept"},{"id":"v1.0-dev-26-builds-8","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"26-builds","chapterTitle":"Build — from code to Docker image","heading":"What is never deleted","snippet":"Even beyond the N most recent, an image is always kept if:\n\n- it's running in one of the app's environments;\n- it was deployed less than 90 days ago, including the image that this deployment replaced ","anchor":"what-is-never-deleted"},{"id":"v1.0-dev-26-builds-9","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"26-builds","chapterTitle":"Build — from code to Docker image","heading":"When and how","snippet":"- The purge runs **every night at 03:30**.\n- It deletes **at most 100 images per night**, across the whole platform. A large first purge can therefore spread over several nights.\n- **A deleted image c","anchor":"when-and-how"},{"id":"v1.0-dev-26-builds-10","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"26-builds","chapterTitle":"Build — from code to Docker image","heading":"Purge in simulation mode","snippet":"The platform can run the purge in simulation mode. In that case, **nothing is deleted**: the purge only works out which images would have gone. The card says so with a message starting with « La purge","anchor":"purge-in-simulation-mode"},{"id":"v1.0-dev-26-builds-11","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"26-builds","chapterTitle":"Build — from code to Docker image","heading":"Badges in the build list","snippet":"| Badge | Meaning |\n|-------|---------|\n| **Déployé · prod, dev** (deployed) | The image is running in environments of these types |\n| **Conservé** (kept) | The purge won't delete this image: it's amo","anchor":"badges-in-the-build-list"},{"id":"v1.0-dev-26-builds-12","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"26-builds","chapterTitle":"Build — from code to Docker image","heading":"Registry quota","snippet":"A platform administrator can set a storage **quota** for an app. By default, there is none.","anchor":"registry-quota"},{"id":"v1.0-dev-26-builds-13","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"26-builds","chapterTitle":"Build — from code to Docker image","heading":"The Registre card","snippet":"The **Registre** (registry) card, at the top of Infra → **Builds**, shows:\n\n- the storage used by the app's images, and when it was measured;\n- if there is a quota: the storage used out of the quota, ","anchor":"the-registre-card"},{"id":"v1.0-dev-26-builds-14","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"26-builds","chapterTitle":"Build — from code to Docker image","heading":"When the quota is reached","snippet":"Wakastart refuses to start a new build of the app, whether it's started from the console, through the API, or automatically. The message is in French:\n\n```\nQuota du registre atteint : X Go utilisés su","anchor":"when-the-quota-is-reached"},{"id":"v1.0-dev-26-builds-15","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"26-builds","chapterTitle":"Build — from code to Docker image","heading":"Freeing up space","snippet":"Turn on the automatic purge (see above). Note: the space of a purged image is only freed by the **registry's weekly cleanup**, on Sunday at 00:00 UTC. Until then, the displayed storage doesn't go down","anchor":"freeing-up-space"},{"id":"v1.0-dev-26-builds-16","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"26-builds","chapterTitle":"Build — from code to Docker image","heading":"Diagnosing a failed build","snippet":"If a Wakastart build ends up `FAILED`, the first thing to do is **reproduce the error locally with `docker build`**. The Wakastart builder runs exactly the same command as you would locally — if it pa","anchor":"diagnosing-a-failed-build"},{"id":"v1.0-dev-27-databases-storage-0","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"27-databases-storage","chapterTitle":"Databases and storage","heading":"Database","snippet":"> **What is it?** A system that stores structured data and lets you query it. It's the core of your app's persistence.\n\nEngines available in Wakastart:\n\n| Engine | Type | Typical use |\n|--------|-----","anchor":"database"},{"id":"v1.0-dev-27-databases-storage-1","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"27-databases-storage","chapterTitle":"Databases and storage","heading":"2 modes: `IN_CLUSTER` vs `MANAGED`","snippet":"| Mode | Where it's hosted | For |\n|------|------------------|-----|\n| **IN_CLUSTER** | In the Wakastart K8s cluster, like a pod | Dev, prototypes, low volume |\n| **MANAGED** | On managed cloud infras","anchor":"2-modes-in_cluster-vs-managed"},{"id":"v1.0-dev-27-databases-storage-2","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"27-databases-storage","chapterTitle":"Databases and storage","heading":"Typical usage pattern","snippet":"```\nDatabaseDefinition \"primary\"\n├── engineType: POSTGRESQL\n├── defaultMode: IN_CLUSTER\n├── defaultPlan: \"essential\"\n└── defaultVersion: \"15\"\n```","anchor":"typical-usage-pattern"},{"id":"v1.0-dev-27-databases-storage-3","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"27-databases-storage","chapterTitle":"Databases and storage","heading":"Storage (Storage Bucket) — S3","snippet":"> **What is an S3 bucket?** A storage system for **files/objects**: images, videos, PDFs, archives, CSV exports… Anything that isn't structured and doesn't need a relational schema.\n\nS3 = \"Simple Stor","anchor":"storage-storage-bucket-s3"},{"id":"v1.0-dev-27-databases-storage-4","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"27-databases-storage","chapterTitle":"Databases and storage","heading":"StorageBucketDefinition / StorageBucketInstance","snippet":"Same pattern as databases: you define it once at the Architecture level, then it's instantiated per environment.\n\nA StorageBucketInstance produces **6 credentials** for the application code:\n\n- `S3_UR","anchor":"storagebucketdefinition-storagebucketinstance"},{"id":"v1.0-dev-28-routing-urls-0","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"28-routing-urls","chapterTitle":"URLs and routing","heading":"Domains (App Domain)","snippet":"| Type | Example | Source |\n|------|---------|--------|\n| **PLATFORM_MANAGED** | `*.wakastart.app` | Managed by Wakastart, automatic SSL certificates, free |\n| **CUSTOM** | `exemple.com` | You bring y","anchor":"domains-app-domain"},{"id":"v1.0-dev-28-routing-urls-1","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"28-routing-urls","chapterTitle":"URLs and routing","heading":"App URL = subdomain + (env prefix) + domain","snippet":"The Wakastart URL pattern inserts the environment slug as a prefix between the subdomain and the root domain — except for prod, which has no prefix.\n\n```\nprod → sous-domaine \"app\" + domaine \"exemp","anchor":"app-url-subdomain-env-prefix-domain"},{"id":"v1.0-dev-28-routing-urls-2","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"28-routing-urls","chapterTitle":"URLs and routing","heading":"Exposing an app at the root of a domain (apex)","snippet":"By default, a URL always requires a subdomain (`app`, `api`…). But if you bring a **CUSTOM** domain (`monsupersite.com`), you may want to expose your app **directly at the root** — on `monsupersite.co","anchor":"exposing-an-app-at-the-root-of-a-domain-apex"},{"id":"v1.0-dev-28-routing-urls-3","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"28-routing-urls","chapterTitle":"URLs and routing","heading":"AppApexUrl (Architecture) → AppApexUrlInstance (per environment)","snippet":"Like the rest of the architecture, the apex is declared **once** and then instantiated **per environment**:\n\n| Level | Resource | What you describe |\n|--------|-----------|------------------|\n| **Arch","anchor":"appapexurl-architecture-appapexurlinstance-per-environment"},{"id":"v1.0-dev-28-routing-urls-4","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"28-routing-urls","chapterTitle":"URLs and routing","heading":"DNS: always an `A`/`AAAA` record, never a `CNAME`","snippet":"A `CNAME` at the root of a zone is structurally invalid (RFC 1034/1912). For any apex hostname, Wakastart therefore automatically forces an `A`/`AAAA` record, regardless of the provider — you have not","anchor":"dns-always-an-aaaaa-record-never-a-cname"},{"id":"v1.0-dev-28-routing-urls-5","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"28-routing-urls","chapterTitle":"URLs and routing","heading":"Mandatory warning at instantiation","snippet":"Exposing a domain at its root writes a DNS record at the root **with no subdomain**. However, Wakastart **does not check** what's currently resolving on that domain: a third-party site already in prod","anchor":"mandatory-warning-at-instantiation"},{"id":"v1.0-dev-28-routing-urls-6","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"28-routing-urls","chapterTitle":"URLs and routing","heading":"HttpRoute = a URL's internal routing","snippet":"An HttpRoute is attached to a URL, saying \"send everything under `/api/*` to the backend ServiceInstance, everything under `/` to the frontend ServiceInstance.\" This is application-level routing (equi","anchor":"httproute-a-urls-internal-routing"},{"id":"v1.0-dev-28-routing-urls-7","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"28-routing-urls","chapterTitle":"URLs and routing","heading":"Official front URL (Primary Front URL)","snippet":"An app can have several routes (`AppRoute`) pointing to several services with the `FRONT` role (web front, mobile front packaged as a PWA, etc.). By default, nothing distinguishes which one is \"the\" r","anchor":"official-front-url-primary-front-url"},{"id":"v1.0-dev-28-routing-urls-8","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"28-routing-urls","chapterTitle":"URLs and routing","heading":"Checking the URL per environment","snippet":"The `GET /app-routes/primary-front-url-by-environment?appId=` endpoint resolves the designated route and computes its FQDN for each of the app's environments:\n\n| Status | Meaning |\n|--------|---------","anchor":"checking-the-url-per-environment"},{"id":"v1.0-dev-29-vars-secrets-0","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"29-vars-secrets","chapterTitle":"Variables and Secrets","heading":"1. Architecture: declare what the service expects","snippet":"When you create a ServiceDefinition, you list the variables your service consumes:\n\n```\nServiceDefinition \"backend\"\n├── requires JWT_SECRET\n├── requires DATABASE_URL\n├── requires S3_BUCKET\n└── require","anchor":"1-architecture-declare-what-the-service-expects"},{"id":"v1.0-dev-29-vars-secrets-1","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"29-vars-secrets","chapterTitle":"Variables and Secrets","heading":"2. Configuration of an environment","snippet":"The **Configuration** of an environment is the **inventory of values available** in that env, from which your services can draw. It is **shared across all services in the environment**.","anchor":"2-configuration-of-an-environment"},{"id":"v1.0-dev-29-vars-secrets-2","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"29-vars-secrets","chapterTitle":"Variables and Secrets","heading":"Where Configuration entries come from","snippet":"| Source | Example | Managed by |\n|--------|---------|----------|\n| **Platform** | Internal URL of a Wakastart service (Discovery, IAM…) | Wakastart (auto-generated, dynamic) |\n| **Environment** | URL","anchor":"where-configuration-entries-come-from"},{"id":"v1.0-dev-29-vars-secrets-3","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"29-vars-secrets","chapterTitle":"Variables and Secrets","heading":"Secret vs non-secret","snippet":"Each configuration entry can be marked **secret** or not:\n\n| | Readable after creation | Visible in the UI | Typical use |\n|--|----------------------|-------------------|---------------|\n| **Non-secre","anchor":"secret-vs-non-secret"},{"id":"v1.0-dev-29-vars-secrets-4","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"29-vars-secrets","chapterTitle":"Variables and Secrets","heading":"3. Binding: connecting a service to the Configuration","snippet":"For each ServiceInstance, you create a **binding** between a variable expected by the service (declared in its ServiceDefinition) and an entry in the env's Configuration.\n\n```\nServiceInstance \"backend","anchor":"3-binding-connecting-a-service-to-the-configuration"},{"id":"v1.0-dev-29-vars-secrets-5","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"29-vars-secrets","chapterTitle":"Variables and Secrets","heading":"Pooling: one value, multiple services","snippet":"If several services need the **same** value (e.g. `STRIPE_API_KEY` used by `backend` and `worker`), **don't create two identical entries**. Create **a single entry** in the env's Configuration and bin","anchor":"pooling-one-value-multiple-services"},{"id":"v1.0-dev-29-vars-secrets-6","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"29-vars-secrets","chapterTitle":"Variables and Secrets","heading":"Platform variables are dynamic","snippet":"Entries generated by the platform or by the environment (DB URL, internal service URL, public hostname of another service in the app, S3 credentials…) are **dynamic**: if the underlying resource chang","anchor":"platform-variables-are-dynamic"},{"id":"v1.0-dev-37-url-redirects-0","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"37-url-redirects","chapterTitle":"URL Redirects","heading":"Source block — immutable after creation","snippet":"| Field | Description |\n|-------|--------------|\n| **Domain** | A `CUSTOM` domain belonging to the app, or a `PLATFORM_MANAGED` domain shared across the whole platform (e.g. `y.wakastart.app` on dev) ","anchor":"source-block-immutable-after-creation"},{"id":"v1.0-dev-37-url-redirects-1","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"37-url-redirects","chapterTitle":"URL Redirects","heading":"Destination block — editable at any time","snippet":"| Field | Description |\n|-------|--------------|\n| **Route (AppRoute)** | Existing route of the app to target |\n| **Environment** | Environment in which the route is provisioned |\n| **Path** | Path ap","anchor":"destination-block-editable-at-any-time"},{"id":"v1.0-dev-37-url-redirects-2","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"37-url-redirects","chapterTitle":"URL Redirects","heading":"Statuses","snippet":"Standard Wakastart resource lifecycle:\n\n| Status | Meaning |\n|--------|----------------|\n| `PENDING` | Redirect created in the DB, awaiting processing by the operator |\n| `PROVISIONING` | K8s resource","anchor":"statuses"},{"id":"v1.0-dev-37-url-redirects-3","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"37-url-redirects","chapterTitle":"URL Redirects","heading":"Technical mechanism","snippet":"Wakastart's classic application routing goes through Gateway API + Istio, via an `HttpRoute` with a `RequestRedirectFilter` filter for simple redirects. This mechanism **is not sufficient** here: Gate","anchor":"technical-mechanism"},{"id":"v1.0-dev-37-url-redirects-4","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"37-url-redirects","chapterTitle":"URL Redirects","heading":"App-scale redirects (App-scope)","snippet":"The `NETWORK` and `CUSTOMER` scopes above address tenants downstream of the app. The **`APP`** scope answers a different need: allowing **the app team itself** to redirect one URL to another within it","anchor":"app-scale-redirects-app-scope"},{"id":"v1.0-dev-37-url-redirects-5","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"37-url-redirects","chapterTitle":"URL Redirects","heading":"AppUrlRedirect (Architecture) → AppUrlRedirectInstance (per environment)","snippet":"Like the rest of the architecture, an App-scope redirect is declared **once**, without ever choosing an environment, then instantiated **per environment**:\n\n| Level | Resource | What you describe |\n|-","anchor":"appurlredirect-architecture-appurlredirectinstance-per-environment"},{"id":"v1.0-dev-37-url-redirects-6","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"37-url-redirects","chapterTitle":"URL Redirects","heading":"Same technical mechanism","snippet":"An App-scope redirect reuses exactly the **shared HAProxy** component (`wakastart-redirects`) described above: same standard resources on the infra API side (`DnsRecord`, `ListenerSet`, `HttpRoute` po","anchor":"same-technical-mechanism"},{"id":"v1.0-dev-37-url-redirects-7","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"37-url-redirects","chapterTitle":"URL Redirects","heading":"Known limitations","snippet":"- **RBAC**: no fine-grained access control beyond `WakaAdmin` / `OwnerAdmin` (full access to redirects), in addition to the standard Network/Customer partitioning.\n- **Cap**: 20 redirects maximum per ","anchor":"known-limitations"},{"id":"v1.0-dev-30-environments-0","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"30-environments","chapterTitle":"Environments","heading":"Main fields of an environment","snippet":"| Field | Example | Role |\n|-------|---------|------|\n| `env` | `dev` / `prod` / `staging` | Environment type |\n| `shortname` | `exemple` | Short nickname of the app in this env |\n| `slug` | `exemple-","anchor":"main-fields-of-an-environment"},{"id":"v1.0-dev-30-environments-1","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"30-environments","chapterTitle":"Environments","heading":"Lifecycle of an env","snippet":"```\nACTIVE → (pause) → PAUSED → (resume) → ACTIVE\n ↓\nDELETING → (cleanup) → deleted\n```","anchor":"lifecycle-of-an-env"},{"id":"v1.0-dev-30-environments-2","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"30-environments","chapterTitle":"Environments","heading":"The environment dashboard","snippet":"When you click on an environment, you get access to:\n\n| Tab | Content |\n|--------|---------|\n| **Summary** | Overview (services up, last deploy, health) |\n| **Services** | List of ServiceInstances wit","anchor":"the-environment-dashboard"},{"id":"v1.0-dev-32-builds-vs-deployments-0","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"32-builds-vs-deployments","chapterTitle":"Builds vs Deployments","heading":"Typical workflow","snippet":"1. You commit code and push to `main`\n2. Wakastart **builds**: `main` HEAD → image `:abc123`\n3. Once `SUCCEEDED`, in AUTO mode, the image is **deployed** to the environments watching `main`\n4. Wakasta","anchor":"typical-workflow"},{"id":"v1.0-dev-32-builds-vs-deployments-1","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"32-builds-vs-deployments","chapterTitle":"Builds vs Deployments","heading":"Deployment modes (DeploymentMode)","snippet":"| Mode | Behavior |\n|------|--------------|\n| `AUTO` | Auto-deploy as soon as a build on the watched branch succeeds |\n| `MANUAL` | You explicitly choose when to deploy (and which image) |","anchor":"deployment-modes-deploymentmode"},{"id":"v1.0-dev-33-workflow-complete-0","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"33-workflow-complete","chapterTitle":"Complete Workflow — Creating an App from Scratch","heading":"Step 1 — Create the App","snippet":"You go into the UI, \"New App\", you give it a name. Wakastart creates:\n\n- The `App` record in the DB\n- A dedicated space in the registry for your future Docker images\n- A dedicated space in the secrets","anchor":"step-1-create-the-app"},{"id":"v1.0-dev-33-workflow-complete-1","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"33-workflow-complete","chapterTitle":"Complete Workflow — Creating an App from Scratch","heading":"Step 2 — Define the Architecture","snippet":"You navigate to **Infra → Architecture**. You create:\n\n1. **A managed Repository** `exemple-backend` (Wakastart creates the repo on GitHub via the `Waka-Start` org)\n2. **A ServiceDefinition** `backend","anchor":"step-2-define-the-architecture"},{"id":"v1.0-dev-33-workflow-complete-2","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"33-workflow-complete","chapterTitle":"Complete Workflow — Creating an App from Scratch","heading":"Step 3 — Create an environment","snippet":"You create a `dev` environment:\n\n- gitRef: `main`\n- autoDeploy: true\n\n→ Wakastart creates for this environment:\n\n- A dedicated Kubernetes namespace that isolates the env's resources\n- The DatabaseInst","anchor":"step-3-create-an-environment"},{"id":"v1.0-dev-33-workflow-complete-3","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"33-workflow-complete","chapterTitle":"Complete Workflow — Creating an App from Scratch","heading":"Step 4 — Build and deploy","snippet":"You commit code, you push to `main`. Wakastart:\n\n1. Detects the push via a GitHub webhook\n2. Creates a **Build** in PENDING\n3. The build moves through BUILDING → PUSHING → SUCCEEDED\n4. In AUTO mode → ","anchor":"step-4-build-and-deploy"},{"id":"v1.0-dev-33-workflow-complete-4","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"33-workflow-complete","chapterTitle":"Complete Workflow — Creating an App from Scratch","heading":"Step 5 — Promote to prod","snippet":"You create a `prod` environment:\n\n- gitRef: `prod` (dedicated branch)\n- autoDeploy: true\n- You override your DatabaseInstance: `mode: MANAGED` (managed PostgreSQL, HA + auto backups)\n- You add a custo","anchor":"step-5-promote-to-prod"},{"id":"v1.0-dev-33-workflow-complete-5","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"33-workflow-complete","chapterTitle":"Complete Workflow — Creating an App from Scratch","heading":"Frequently asked questions","snippet":"**\"Why is there a Definition / Instance distinction?\"**\n→ So that you can define your architecture **once** and duplicate it across multiple environments with local overrides (cheaper plan in dev, mor","anchor":"frequently-asked-questions"},{"id":"v1.0-dev-34-deployment-practices-0","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"34-deployment-practices","chapterTitle":"Deployment Best Practices","heading":"1. Environment variables","snippet":"Each `.env.example` file constitutes a **configuration contract**. It must be exhaustive, self-documented, and kept up to date with every evolution of the project.","anchor":"1-environment-variables"},{"id":"v1.0-dev-34-deployment-practices-1","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"34-deployment-practices","chapterTitle":"Deployment Best Practices","heading":"1.1 Mandatory rules for each variable","snippet":"| Icon | Attribute | Requirement |\n|---|---|---|\n| 📝 | Example value | Provide a real, functional example value. No empty placeholder like `xxx` or `changeme`. |\n| 📌 | Contextual description | Expla","anchor":"11-mandatory-rules-for-each-variable"},{"id":"v1.0-dev-34-deployment-practices-2","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"34-deployment-practices","chapterTitle":"Deployment Best Practices","heading":"1.2 Documentation example","snippet":"```env\n# URL of the backend API consumed by the frontend.\n# TYPE: public URL (accessible from the user's browser).\n# REQUIRED — without this variable, all API requests fail.\n# DUPLICATE: This variable","anchor":"12-documentation-example"},{"id":"v1.0-dev-34-deployment-practices-3","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"34-deployment-practices","chapterTitle":"Deployment Best Practices","heading":"1.3 `NEXT_PUBLIC_*` vs runtime variables (Next.js)","snippet":"`NEXT_PUBLIC_*` variables are **compiled at build time** by Next.js and inlined into the JS bundle. They cannot be changed at container runtime.\n\nIf a URL needs to be configurable without a rebuild (e","anchor":"13-next_public_-vs-runtime-variables-nextjs"},{"id":"v1.0-dev-34-deployment-practices-4","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"34-deployment-practices","chapterTitle":"Deployment Best Practices","heading":"2. Dockerfile and Prisma migrations","snippet":"In the absence of advanced CI/CD tooling, any application requiring a database must guarantee that Prisma migrations are applied automatically when the container starts.","anchor":"2-dockerfile-and-prisma-migrations"},{"id":"v1.0-dev-34-deployment-practices-5","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"34-deployment-practices","chapterTitle":"Deployment Best Practices","heading":"2.1 Mandatory entrypoint for applications using Prisma","snippet":"The Dockerfile of any backend application using Prisma must delegate startup to an `entrypoint.sh` script. This script applies migrations before starting the main Node.js process.\n\n**Typical structure","anchor":"21-mandatory-entrypoint-for-applications-using-prisma"},{"id":"v1.0-dev-34-deployment-practices-6","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"34-deployment-practices","chapterTitle":"Deployment Best Practices","heading":"2.2 Pitfalls to avoid","snippet":"- ✅ `prisma` must be listed in `dependencies` (and **not** `devDependencies`) to be available when the production container runs.\n- 🚨 **Never** use `pnpm prune --prod` without having verified that `p","anchor":"22-pitfalls-to-avoid"},{"id":"v1.0-dev-34-deployment-practices-7","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"34-deployment-practices","chapterTitle":"Deployment Best Practices","heading":"2.3 Optional seed: injecting initial or test data","snippet":"Your service's container is the only entry point to its live database. To **re-inject data** (reference dataset, demo data, or your local environment's test data) into a Wakastart deployment, the righ","anchor":"23-optional-seed-injecting-initial-or-test-data"},{"id":"v1.0-dev-34-deployment-practices-8","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"34-deployment-practices","chapterTitle":"Deployment Best Practices","heading":"3. TypeScript and NestJS / Node.js build","snippet":"TypeScript build errors are a frequent cause of silently broken deployments.\n\n| Rule | Detail |\n|---|---|\n| **`rootDir` required** in `tsconfig.build.json` | Always declare `rootDir: \"./src\"` to guara","anchor":"3-typescript-and-nestjs-nodejs-build"},{"id":"v1.0-dev-34-deployment-practices-9","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"34-deployment-practices","chapterTitle":"Deployment Best Practices","heading":"4. Frontend runtime config (Next.js)","snippet":"Next.js applications deployed as containers have two configuration sources: `NEXT_PUBLIC_*` variables (compiled at build time) and variables injected at runtime via `window.__RUNTIME_CONFIG__`. Variab","anchor":"4-frontend-runtime-config-nextjs"},{"id":"v1.0-dev-34-deployment-practices-10","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"34-deployment-practices","chapterTitle":"Deployment Best Practices","heading":"Rules for runtime config","snippet":"- The frontend's `entrypoint.sh` must read variables **exactly as defined in the K8s deployment** (`NEXT_PUBLIC_API_URL`, `KEYCLOAK_PUBLIC_URL`, etc.), and **not** locally invented aliases (`API_URL`,","anchor":"rules-for-runtime-config"},{"id":"v1.0-dev-34-deployment-practices-11","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"34-deployment-practices","chapterTitle":"Deployment Best Practices","heading":"5. S3 and Object Storage integration","snippet":"S3 adapters must correctly handle endpoint URLs to avoid silent connectivity errors.","anchor":"5-s3-and-object-storage-integration"},{"id":"v1.0-dev-34-deployment-practices-12","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"34-deployment-practices","chapterTitle":"Deployment Best Practices","heading":"Rules for S3 endpoints","snippet":"- **Never** mechanically prefix `https://` onto an endpoint variable: if the variable already contains the protocol, double-prefixing produces an invalid URL (`https://https://…`) that linters cannot ","anchor":"rules-for-s3-endpoints"},{"id":"v1.0-dev-34-deployment-practices-13","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"34-deployment-practices","chapterTitle":"Deployment Best Practices","heading":"6. Authentication and OAuth / Keycloak flow","snippet":"> See also [Authentication — Concepts & Flow](/v1.0/dev/03-authentication-overview) for the general OAuth flow. The rules below are **concrete pitfalls** encountered on production services.","anchor":"6-authentication-and-oauth-keycloak-flow"},{"id":"v1.0-dev-34-deployment-practices-14","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"34-deployment-practices","chapterTitle":"Deployment Best Practices","heading":"6.1 `redirect_uri`","snippet":"The `redirect_uri` sent in the authorization request must be **strictly identical** to the one used during the server-side code exchange. Any discrepancy causes Keycloak to reject it.\n\nThe server must","anchor":"61-redirect_uri"},{"id":"v1.0-dev-34-deployment-practices-15","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"34-deployment-practices","chapterTitle":"Deployment Best Practices","heading":"6.2 `sessionStorage` keys","snippet":"All `sessionStorage` keys used in the OAuth flow (`realm`, `client_id`, `state`, `code_verifier`…) must be declared in a **shared constants file** across all involved modules. Scattered string literal","anchor":"62-sessionstorage-keys"},{"id":"v1.0-dev-34-deployment-practices-16","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"34-deployment-practices","chapterTitle":"Deployment Best Practices","heading":"6.3 `login_hint`","snippet":"When the user's email is known before redirecting to Keycloak, pass the standard OIDC `login_hint` parameter to pre-fill the Keycloak form and avoid double entry.","anchor":"63-login_hint"},{"id":"v1.0-dev-34-deployment-practices-17","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"34-deployment-practices","chapterTitle":"Deployment Best Practices","heading":"6.4 Multi-organization (Discovery)","snippet":"If the Discovery API can return multiple accounts for the same email (multiple Keycloak realms), the frontend must display an **organization selection** screen before redirecting. Never blindly take `","anchor":"64-multi-organization-discovery"},{"id":"v1.0-dev-34-deployment-practices-18","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"34-deployment-practices","chapterTitle":"Deployment Best Practices","heading":"6.5 Keycloak URL on the server side","snippet":"The `KEYCLOAK_URL` variable (internal or public URL for server-side calls) must be **explicitly defined** in the K8s configuration. Without it, calls fall back to `localhost:8080` and fail silently.\n\n","anchor":"65-keycloak-url-on-the-server-side"},{"id":"v1.0-dev-34-deployment-practices-19","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"34-deployment-practices","chapterTitle":"Deployment Best Practices","heading":"7. Prisma migrations (beyond runtime)","snippet":"Database migrations must be managed deterministically and reproducibly across environments.","anchor":"7-prisma-migrations-beyond-runtime"},{"id":"v1.0-dev-34-deployment-practices-20","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"34-deployment-practices","chapterTitle":"Deployment Best Practices","heading":"Rules for Prisma migrations","snippet":"- The `prisma/migrations/` directory must contain an **initial migration** generated by `prisma migrate dev` that creates the entire schema. Loose SQL scripts not managed by Prisma are not acceptable.","anchor":"rules-for-prisma-migrations"},{"id":"v1.0-dev-35-glossary-deploy-0","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"35-glossary-deploy","chapterTitle":"Hosting Glossary","heading":"General concepts","snippet":"- **PaaS** (Platform as a Service): you code your app, the platform hosts it — it provides the infra, the OS, the runtime, and the deployment pipeline. Opposite: IaaS (you manage the VMs).\n- **Kuberne","anchor":"general-concepts"},{"id":"v1.0-dev-35-glossary-deploy-1","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"35-glossary-deploy","chapterTitle":"Hosting Glossary","heading":"Images and registry","snippet":"- **Docker image**: a frozen package containing your code + its dependencies + the minimal OS needed to run. Reproducible.\n- **Registry**: a store for Docker images. Wakastart provides a private regis","anchor":"images-and-registry"},{"id":"v1.0-dev-35-glossary-deploy-2","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"35-glossary-deploy","chapterTitle":"Hosting Glossary","heading":"Storage","snippet":"- **S3 Bucket**: a container for files (objects) accessible over HTTP, identified by a unique name. No real folder hierarchy, just keys.\n- **Relational DB** (PostgreSQL, MySQL): tables, columns, joins","anchor":"storage"},{"id":"v1.0-dev-35-glossary-deploy-3","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"35-glossary-deploy","chapterTitle":"Hosting Glossary","heading":"Security","snippet":"- **Secret manager**: an encrypted vault that stores sensitive credentials (DB passwords, API keys, certificates). Wakastart provides one, isolated per app. You never access it directly: the platform ","anchor":"security"},{"id":"v1.0-dev-35-glossary-deploy-4","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"35-glossary-deploy","chapterTitle":"Hosting Glossary","heading":"Network","snippet":"- **Gateway**: the platform's entry point for incoming HTTP traffic. It terminates TLS (certificates) and applies HttpRoute routing rules.\n- **HttpRoute**: a routing rule that says \"this path → this s","anchor":"network"},{"id":"v1.0-dev-35-glossary-deploy-5","version":"v1.0","sectionId":"dev","sectionLabel":"Developer","chapterId":"35-glossary-deploy","chapterTitle":"Hosting Glossary","heading":"CI/CD","snippet":"- **CI** (Continuous Integration): automated tests on every commit. Not managed by Wakastart (you use GitHub Actions, Jenkins, etc.).\n- **CD** (Continuous Deployment): automatic deployment after a suc","anchor":"cicd"}],"groupsBySectionId":{"user":[{"id":"premiers-pas","label":"Getting started","icon":"Rocket","chapters":[{"id":"01-getting-started","version":"v1.0","section":"user","title":"Login and authentication","description":"How to log in to WakaStart: entering your email, selecting your organization, password, and first access.","order":1,"group":"premiers-pas","icon":"LogIn","content":"$11"}]},{"id":"tableau-de-bord","label":"Dashboard","icon":"LayoutDashboard","chapters":[{"id":"02-dashboard","version":"v1.0","section":"user","title":"Main dashboard","description":"Overview of the WakaStart dashboard: KPIs, activity feed, header, and the global AdminCrumb filter.","order":2,"group":"tableau-de-bord","icon":"LayoutDashboard","content":"$12"}]},{"id":"organisation","label":"Organization","icon":"Building2","chapters":[{"id":"03-partners","version":"v1.0","section":"user","title":"Partners","description":"Create, modify, and manage the partners of the WakaStart platform.","order":3,"group":"organisation","icon":"Handshake","content":"$13"},{"id":"04-networks","version":"v1.0","section":"user","title":"Networks","description":"Manage the networks of your WakaStart platform: creation, configuration, and detail page.","order":4,"group":"organisation","icon":"Network","content":"$14"},{"id":"05-customers","version":"v1.0","section":"user","title":"Customers","description":"Create, configure, and manage the customer organizations of your network.","order":5,"group":"organisation","icon":"Building","content":"$15"},{"id":"06-users","version":"v1.0","section":"user","title":"Users","description":"Manage administrator users and Customer accounts: creation, permissions, HDS roles, and profiles.","order":6,"group":"organisation","icon":"Users","content":"$16"},{"id":"07-teams","version":"v1.0","section":"user","title":"Teams","description":"Group a customer's users into teams with differentiated access levels.","order":7,"group":"organisation","icon":"UsersRound","content":"$17"}]},{"id":"applications","label":"Applications","icon":"AppWindow","chapters":[{"id":"08-applications","version":"v1.0","section":"user","title":"Applications","description":"Create, configure, and deploy applications on the WakaStart platform.","order":8,"group":"applications","icon":"AppWindow","content":"$18"},{"id":"09-profiles-rights","version":"v1.0","section":"user","title":"Profiles and rights","description":"Manage application profiles and rights to control access to features.","order":9,"group":"applications","icon":"ShieldCheck","content":"$19"},{"id":"10-api-keys","version":"v1.0","section":"user","title":"API Keys","description":"Create and manage API keys for programmatic access to WakaStart services.","order":10,"group":"applications","icon":"KeyRound","content":"$1a"}]},{"id":"support","label":"Support & tracking","icon":"Ticket","chapters":[{"id":"27-tickets","version":"v1.0","section":"user","title":"Ticket management","description":"Track support and development tickets tied to your applications: creation, statuses, comments, attachments and history.","order":27,"group":"support","icon":"Ticket","content":"$1b"}]},{"id":"securite-conformite","label":"Security & compliance","icon":"ShieldCheck","chapters":[{"id":"11-audit-logs","version":"v1.0","section":"user","title":"Audit Logs","description":"View, filter, and export audit logs for the WakaStart platform.","order":11,"group":"securite-conformite","icon":"ScrollText","content":"$1c"},{"id":"15-antivirus","version":"v1.0","section":"user","title":"Antivirus Module","description":"Monitor and administer the antivirus service: quarantine, queue, and policies.","order":15,"group":"securite-conformite","icon":"ShieldAlert","content":"$1d"},{"id":"20-hds","version":"v1.0","section":"user","title":"HDS Module","description":"Health Data Hosting: overview, transactions, integrity audit, security, and compliance.","order":20,"group":"securite-conformite","icon":"HeartPulse","content":"$1e"},{"id":"16-stellar","version":"v1.0","section":"user","title":"Stellar Module (blockchain proofs)","description":"View integrity proofs anchored on the Stellar blockchain.","order":16,"group":"securite-conformite","icon":"Star","content":"$1f"}]},{"id":"business","label":"Business","icon":"TrendingUp","chapters":[{"id":"12-credits","version":"v1.0","section":"user","title":"Credits","description":"Track your organization's credit consumption and balance.","order":12,"group":"business","icon":"Coins","content":"$20"},{"id":"13-billing","version":"v1.0","section":"user","title":"Billing","description":"Buy credits and manage the billing of your WakaStart account.","order":13,"group":"business","icon":"CreditCard","content":"$21"},{"id":"17-projects","version":"v1.0","section":"user","title":"Projects","description":"Create and manage WakaStart projects: list, editor, team, timeline and document management.","order":17,"group":"business","icon":"FolderKanban","content":"$22"},{"id":"21-prospects","version":"v1.0","section":"user","title":"Prospects and Sales Management","description":"Track sales opportunities, create quotes, and estimate the costs of a WakaStart project.","order":21,"group":"business","icon":"TrendingUp","content":"$23"},{"id":"22-entities","version":"v1.0","section":"user","title":"Legal Entities and Contacts","description":"Manage the directory of client organizations and their contacts.","order":22,"group":"business","icon":"Landmark","content":"$24"},{"id":"25-pricing","version":"v1.0","section":"user","title":"Pricing Module","description":"Define the credit cost of each action on the platform, with special rates by network or client.","order":25,"group":"business","icon":"Tag","content":"$25"}]},{"id":"personnalisation","label":"Customization","icon":"Palette","chapters":[{"id":"14-media","version":"v1.0","section":"user","title":"Media","description":"Manage the platform's media files, configure the service, and track processing.","order":14,"group":"personnalisation","icon":"Image","content":"\n# Media\n\n> This section lets you manage the multimedia files (images, videos, documents) used by your applications, and track their processing.\n\n## When do you use this section?\n\n- You want to **view or administer** the platform's media files\n- You need to **configure the media management service**\n- You want to **track the status of ongoing processing** (conversion, resizing, analysis...)\n\n## Accessing media management\n\nFrom the main menu on the left, click **Media**.\n\nTwo subsections are available:\n\n### Media service configuration\n\nAccess the service's configuration settings: supported formats, maximum file size, automatic processing options.\n\n### Ongoing and completed processing\n\nView the list of processing operations (conversion, resizing, antivirus analysis...) with their status: pending, in progress, or completed. Any errors are clearly flagged so you can take action.\n\n## Learn more\n\n- [Antivirus Module — file analysis](./antivirus)\n- [Backup and restore](./backup)\n"},{"id":"18-settings","version":"v1.0","section":"user","title":"Settings","description":"Configure appearance, cloud providers, and network and customer features.","order":18,"group":"personnalisation","icon":"Settings","content":"$26"},{"id":"23-identity-providers","version":"v1.0","section":"user","title":"Identity Providers (SSO)","description":"Configure SSO connections from external directories: Google, Microsoft, Okta, SAML 2.0.","order":23,"group":"personnalisation","icon":"KeySquare","content":"$27"}]},{"id":"administration-plateforme","label":"Platform administration","icon":"Server","chapters":[{"id":"24-backup","version":"v1.0","section":"user","title":"Backup and Restore","description":"Export and import application, network, and customer configurations via blueprints.","order":24,"group":"administration-plateforme","icon":"DatabaseBackup","content":"$28"},{"id":"26-wakaadmin","version":"v1.0","section":"user","title":"Platform Administration (WakaAdmin)","description":"Advanced platform administration: domains, gateways, container registry, secrets vault, repositories, SMTP, and monitoring.","order":26,"group":"administration-plateforme","icon":"Server","content":"$29"}]},{"id":"compte-personnel","label":"Personal account","icon":"UserCircle","chapters":[{"id":"19-profile","version":"v1.0","section":"user","title":"My Profile","description":"Edit your personal information, preferences, and view your rights in WakaStart.","order":19,"group":"compte-personnel","icon":"UserCircle","content":"$2a"}]},{"id":"annexe","label":"Appendix","icon":"BookMarked","chapters":[{"id":"99-glossary","version":"v1.0","section":"user","title":"Glossary","description":"Definitions of the key terms and concepts of the WakaStart platform.","order":99,"group":"annexe","icon":"BookMarked","content":"$2b"}]}],"dev":[{"id":"premiers-pas","label":"Getting started","icon":"Rocket","chapters":[{"id":"01-architecture","version":"v1.0","section":"dev","title":"Architecture","description":"Overview of the Wakapp architecture: multi-tenant hierarchy, services, communication flows and access modes.","order":1,"group":"premiers-pas","icon":"GitGraph","content":"$2c"},{"id":"02-discovery","version":"v1.0","section":"dev","title":"Discovery — Identifying the user","description":"Using the Discovery service to resolve a user's organization before authentication.","order":2,"group":"premiers-pas","icon":"Search","content":"$2d"}]},{"id":"authentification","label":"Authentication","icon":"Lock","chapters":[{"id":"03-authentication-overview","version":"v1.0","section":"dev","title":"Authentication — Concepts & Flow","description":"Overview of the Wakastart OAuth2 PKCE flow: key concepts, complete diagram and Keycloak prerequisites.","order":3,"group":"authentification","icon":"Lock","content":"$2e"},{"id":"04-authentication-implementation","version":"v1.0","section":"dev","title":"Authentication — PKCE Implementation","description":"Complete PKCE flow code: generation, start-login, exchange, enrichment, cookies and logout.","order":4,"group":"authentification","icon":"KeyRound","content":"$2f"},{"id":"05-me-endpoint-payload","version":"v1.0","section":"dev","title":"User context — /me payload structure","description":"Complete structure of the /me payload: identity, access levels, teams, application rights and features.","order":5,"group":"authentification","icon":"UserCheck","content":"$30"},{"id":"06-me-endpoint-caching","version":"v1.0","section":"dev","title":"User context — Cache & Invalidation","description":"When to call /me, React caching strategy, invalidation after token refresh and best practices.","order":6,"group":"authentification","icon":"RefreshCw","content":"$31"}]},{"id":"securite","label":"Security","icon":"ShieldCheck","chapters":[{"id":"07-access-control-model","version":"v1.0","section":"dev","title":"Access control — Model & Cascade","description":"Wakastart's 2 rights vectors: adminLevel and appRights (resource.action rights), and enabled-feature checks.","order":7,"group":"securite","icon":"ShieldCheck","content":"$32"},{"id":"08-access-control-implementation","version":"v1.0","section":"dev","title":"Access control — Guards & Hooks","description":"Full implementation: useAppRights hook, Protected component, NestJS AppRightGuard.","order":8,"group":"securite","icon":"Shield","content":"$33"},{"id":"09-access-control-features","version":"v1.0","section":"dev","title":"Access control — Feature Flags","description":"App/Network/Customer feature cascade, conditional activation and integration in guards.","order":9,"group":"securite","icon":"ToggleLeft","content":"$34"},{"id":"12-best-practices-security","version":"v1.0","section":"dev","title":"Best Practices — Security","description":"Tokens, secrets, HTTPS, CSP, logs: the non-negotiable security rules for a Wakapp in production.","order":12,"group":"securite","icon":"CheckCircle","content":"$35"},{"id":"13-best-practices-perf-observability","version":"v1.0","section":"dev","title":"Best Practices — Performance & Observability","description":"Cache, proactive refresh, pagination, TanStack Query, Prometheus metrics, and structured logging.","order":13,"group":"securite","icon":"Activity","content":"$36"},{"id":"17-pitfalls","version":"v1.0","section":"dev","title":"Common integration pitfalls","description":"The 10 most frequent mistakes when integrating a Wakapp: symptom, cause and solution.","order":17,"group":"securite","icon":"Bug","content":"$37"}]},{"id":"utilisation","label":"Using the API","icon":"Plug","chapters":[{"id":"10-api-conventions","version":"v1.0","section":"dev","title":"Using the API — REST Conventions","description":"Authenticating requests, pagination, filters, automatic multi-tenancy, and unified error format.","order":10,"group":"utilisation","icon":"Plug","content":"$38"},{"id":"11-api-headers-rate-limits","version":"v1.0","section":"dev","title":"API Usage — Headers & Rate Limits","description":"Required and optional headers, idempotency, CORS, rate limiting and exponential backoff.","order":11,"group":"utilisation","icon":"Gauge","content":"$39"},{"id":"14-endpoint-reference","version":"v1.0","section":"dev","title":"Endpoint reference","description":"Exhaustive table of all Discovery, Auth, profile, CRUD, invitations and modules endpoints available for a WakaApp.","order":14,"group":"utilisation","icon":"BookOpen","content":"$3a"},{"id":"15-errors-http","version":"v1.0","section":"dev","title":"Errors — HTTP Codes","description":"Unified error format, HTTP codes 400 to 5xx, causes and handling strategies for a robust Wakapp.","order":15,"group":"utilisation","icon":"AlertTriangle","content":"$3b"},{"id":"16-errors-business","version":"v1.0","section":"dev","title":"Errors — Business Codes","description":"Wakastart business error codes, exact messages that can be tested programmatically, and status mappings.","order":16,"group":"utilisation","icon":"AlertCircle","content":"$3c"}]},{"id":"modules","label":"Modules","icon":"Blocks","chapters":[{"id":"18-invitations-create","version":"v1.0","section":"dev","title":"Invitations API — Creation","description":"Create an invitation: prerequisites, POST /api/invitations endpoint, body, response and error handling.","order":18,"group":"modules","icon":"Mail","content":"$3d"},{"id":"19-invitations-verify-accept","version":"v1.0","section":"dev","title":"Invitations API — Verification & Acceptance","description":"The verify and accept endpoints: implementing the acceptance page, server-side effects and pitfalls.","order":19,"group":"modules","icon":"UserPlus","content":"$3e"},{"id":"20-mcp-server-overview","version":"v1.0","section":"dev","title":"MCP Server — Overview","description":"The WakaStart MCP server hosted on docs.wakastart.app: 5 tools, available resources and technical characteristics.","order":20,"group":"modules","icon":"Bot","content":"$3f"},{"id":"21-mcp-server-claude-code-setup","version":"v1.0","section":"dev","title":"MCP Server — Claude Code Configuration","description":"Configure Claude Code with .mcp.json to access the WakaStart MCP server at docs.wakastart.app.","order":21,"group":"modules","icon":"Settings","content":"$40"}]},{"id":"modele-architecture","label":"Architecture model","icon":"LayoutDashboard","chapters":[{"id":"22-platform-overview","version":"v1.0","section":"dev","title":"Platform Overview","description":"Wakastart is a PaaS platform that hosts your app — you declare its components, Wakastart builds and runs them.","order":22,"group":"modele-architecture","icon":"LayoutDashboard","content":"\n# Platform Overview\n\n## 📍 Where to access the Infra section in the UI\n\n**Applications** menu → click on your app → the **🚀 green rocket** icon on the app card opens the **Infra / Hosting** area dedicated to that app.\n\nThis is the entry point for all hosting features: architecture, builds, environments, databases, URLs, variables.\n\nWakastart is a PaaS (Platform as a Service) platform that **hosts your apps**. You declare your application's components (services, databases, dependencies); Wakastart provisions the infrastructure (databases, S3, DNS, SSL certificates), builds your code into Docker images, and runs the pods on Kubernetes.\n\nThe **Infra** section of the dashboard is where you:\n\n- **Describe** your application (services, databases, dependencies)\n- **Manage** its environments (dev, staging, prod, etc.)\n- **Build** your code into Docker images\n- **Deploy** and **monitor**\n\n## The mantra to remember\n\n> *You declare **what** your app contains.*\n> *Wakastart **builds**, **hosts**, and **runs** it.*\n"},{"id":"23-app-hierarchy","version":"v1.0","section":"dev","title":"App → Environment → Instances Hierarchy","description":"Wakastart's hierarchical model: Architecture (the blueprint) vs Environments (the actual instances).","order":23,"group":"modele-architecture","icon":"GitMerge","content":"$41"}]},{"id":"architecture-json","label":"Architecture as JSON","icon":"FileJson","chapters":[{"id":"36-architecture-json","version":"v1.0","section":"dev","title":"Describing your architecture in JSON","description":"Describe your wakapp's infrastructure in a JSON file and import it in a few clicks — get started fast, clone an app, or let an AI generate the skeleton.","order":36,"group":"architecture-json","icon":"FileJson","content":"$42"}]},{"id":"sources-services","label":"Sources & services","icon":"Package","chapters":[{"id":"24-repositories","version":"v1.0","section":"dev","title":"Repository (Git repository)","description":"Managed or imported repos: the source of the code you'll build.","order":24,"group":"sources-services","icon":"Github","content":"\n# Repository (Git repository)\n\n> 📍 **Where to find this in the UI** — Infra → **Architecture** tab → **Repositories**\n\n> **What is it?** A repository is a source code repository on GitHub. It's where the code you'll build and deploy comes from.\n\nWakastart distinguishes **2 types of repos**:\n\n| Type | Description |\n|------|-------------|\n| **Managed** | Wakastart creates it for you on GitHub (under the `Waka-Start` org). Handy for getting started quickly. |\n| **Imported** | You provide the URL of a repo that already exists elsewhere (e.g. `https://github.com/groupe-jds/biped.git`). Wakastart reads it but doesn't own it. |\n\n## What is a repo used for in Wakastart?\n\nA repo is **not** a service on its own. It provides the source code that will then be:\n\n1. Read to perform a **Build** (turn the code into a Docker image)\n2. Used for its branches/tags (Git reference for an environment)\n\nSeveral services can come from the same repo (monorepo).\n"},{"id":"25-services","version":"v1.0","section":"dev","title":"Service — executable component","description":"ServiceDefinition (architecture) vs ServiceInstance (environment): the 2-level pattern.","order":25,"group":"sources-services","icon":"Box","content":"$43"},{"id":"26-builds","version":"v1.0","section":"dev","title":"Build — from code to Docker image","description":"The pipeline that turns your Git code into a deployable Docker image.","order":26,"group":"sources-services","icon":"Package","content":"$44"}]},{"id":"donnees-routing","label":"Databases, storage, routing","icon":"Database","chapters":[{"id":"27-databases-storage","version":"v1.0","section":"dev","title":"Databases and storage","description":"PostgreSQL, MongoDB, Valkey, and S3 buckets: your app's persistent dependencies.","order":27,"group":"donnees-routing","icon":"Database","content":"$45"},{"id":"28-routing-urls","version":"v1.0","section":"dev","title":"URLs and routing","description":"Domains, subdomains, and HttpRoutes: how Wakastart routes HTTP traffic to your services.","order":28,"group":"donnees-routing","icon":"Globe","content":"$46"},{"id":"29-vars-secrets","version":"v1.0","section":"dev","title":"Variables and Secrets","description":"How Wakastart delivers config to your services: architecture, environment configuration, binding.","order":29,"group":"donnees-routing","icon":"KeyRound","content":"$47"},{"id":"37-url-redirects","version":"v1.0","section":"dev","title":"URL Redirects","description":"Redirect a Network or Customer subdomain to an existing application route, via a shared HAProxy component.","order":37,"group":"donnees-routing","icon":"ArrowRightLeft","content":"$48"}]},{"id":"environnements-lifecycle","label":"Environments & lifecycle","icon":"Layers","chapters":[{"id":"30-environments","version":"v1.0","section":"dev","title":"Environments","description":"An environment = a complete, isolated instance of your app. Main fields, lifecycle, dashboard.","order":30,"group":"environnements-lifecycle","icon":"Layers","content":"$49"},{"id":"31-resource-lifecycle","version":"v1.0","section":"dev","title":"Resource Lifecycle","description":"Statuses PENDING → PROVISIONING → PROVISIONED → DESTROYING → DESTROYED.","order":31,"group":"environnements-lifecycle","icon":"Activity","content":"\n# Resource Lifecycle (status)\n\nEvery resource managed by Wakastart follows a lifecycle:\n\n```\nPENDING → PROVISIONING → PROVISIONED (or READY for DBs)\n ↓\n (modifications)\n ↓\n DESTROYING → DESTROYED\n```\n\n| Status | Meaning |\n|--------|---------------|\n| `PENDING` | Wakastart has noted your request, work is about to start |\n| `PROVISIONING` | Being created (creating GitHub repo, applying terraform, etc.) |\n| `PROVISIONED` / `READY` | Available and usable |\n| `FAILED` | Something went wrong — see `provisioningError` |\n| `DESTROYING` | You deleted it, cleanup in progress |\n| `DESTROYED` | Cleanup complete |\n\n→ You may therefore see a resource move quickly from PENDING to PROVISIONING to PROVISIONED, or stay in PROVISIONING for a few minutes while the platform provisions it (e.g. creating a managed database at the cloud provider).\n"},{"id":"32-builds-vs-deployments","version":"v1.0","section":"dev","title":"Builds vs Deployments","description":"Crucial difference: a Build produces an image, a Deployment launches pods. AUTO vs MANUAL mode.","order":32,"group":"environnements-lifecycle","icon":"GitCompare","content":"$4a"}]},{"id":"workflow","label":"Workflow","icon":"Map","chapters":[{"id":"33-workflow-complete","version":"v1.0","section":"dev","title":"Complete Workflow — Creating an App from Scratch","description":"End-to-end walkthrough: create the App, define the architecture, trigger a build, deploy to dev then to prod.","order":33,"group":"workflow","icon":"Map","content":"$4b"}]},{"id":"bonnes-pratiques","label":"Best practices","icon":"CheckCircle","chapters":[{"id":"34-deployment-practices","version":"v1.0","section":"dev","title":"Deployment Best Practices","description":"Concrete rules for an application service to run correctly on Wakastart: .env.example, Dockerfile, Prisma migrations, data seeding, runtime config, S3, OAuth.","order":34,"group":"bonnes-pratiques","icon":"CheckCircle","content":"$4c"}]},{"id":"glossaire","label":"Glossary","icon":"BookOpen","chapters":[{"id":"35-glossary-deploy","version":"v1.0","section":"dev","title":"Hosting Glossary","description":"Technical vocabulary of hosting: PaaS, K8s, Pod, Docker image, S3 Bucket, Gateway, etc.","order":35,"group":"glossaire","icon":"BookOpen","content":"$4d"}]},{"id":"references","label":"References","icon":"BookMarked","chapters":[{"id":"api-reference","version":"v1.0","section":"dev","title":"API Reference","description":"Interactive OpenAPI spec of the WakaStart Public API — browse endpoints, try requests.","order":13,"group":"references","icon":"FileCode2","content":"\n# API Reference\n\nThis page loads the full OpenAPI specification of the WakaStart Public API into an interactive viewer (Scalar).\n"},{"id":"ui-storybook","version":"v1.0","section":"dev","title":"UI Storybook","description":"Visual documentation of @wakastellar/ui components — interactive examples, props, and variants.","order":14,"group":"references","icon":"Palette","content":"\n# UI Storybook\n\nThis page embeds the Storybook of the `@wakastellar/ui` components used in WakaStart Wakapps.\n"}]}]},"children":"$L4e"}]