# Organisations

> Lister, créer et modifier les réseaux de votre application, et gérer leurs clients jusqu'à la suppression, par l'API publique.

Une application distribue ses services par des [réseaux](/v1.0/glossaire#réseau), qui regroupent des [clients](/v1.0/glossaire#client). Chaque réseau a son propre realm Keycloak ; chaque client correspond à une organisation Keycloak dans ce realm. Le modèle est expliqué dans [Organisation multi-tenant](/v1.0/concepts/organisation-multi-tenant).

**Accès commun** : appelant de niveau Administrateur client (`CUSTOMER_ADMIN`) au minimum, avec le droit applicatif indiqué pour chaque endpoint. L'appelant ne voit et ne modifie que les réseaux et les clients de son périmètre.

## L'objet Réseau

| Champ | Type | Description |
|---|---|---|
| `id` | UUID | Identifiant technique |
| `wid` | chaîne (6) | Identifiant court |
| `appId` | UUID | Application du réseau. Non modifiable |
| `name` | chaîne (100) | Nom affiché |
| `description` | chaîne (250) ou `null` | Description |
| `subdomain` | chaîne (15) ou `null` | Sous-domaine : minuscules, chiffres et tirets |
| `defLangId`, `defThemeId` | UUID ou `null` | Langue et thème par défaut des clients du réseau |
| `status` | chaîne | `ACTIVE`, `INACTIVE`, `SUSPENDED`, `DELETED` ou `DRAFT` |
| `createdAt`, `updatedAt` | chaîne ISO 8601 | Dates de création et de modification |

## L'objet Client

| Champ | Type | Description |
|---|---|---|
| `id` | UUID | Identifiant technique |
| `wid` | chaîne (6) | Identifiant court |
| `networkId` | UUID | Réseau du client. Non modifiable |
| `name` | chaîne (100) | Nom affiché |
| `description` | chaîne (250) ou `null` | Description |
| `subdomain` | chaîne (15) ou `null` | Sous-domaine : minuscules, chiffres et tirets |
| `entityId` | UUID | [Entité juridique](/v1.0/glossaire#entité-juridique) qui porte le client |
| `defLangId`, `defThemeId` | UUID ou `null` | Langue et thème par défaut de ses utilisateurs |
| `allowAutoRegistration` | booléen | Réservé, vaut `false` |
| `status` | chaîne | `ACTIVE`, `INACTIVE`, `SUSPENDED`, `DELETED` ou `DRAFT` |
| `createdAt`, `updatedAt` | chaîne ISO 8601 | Dates de création et de modification |

## Lister les réseaux

::endpoint{method="GET" path="/api/config/networks"}

**Droit requis** : `networks.read`.

| Paramètre de requête | Type | Défaut | Description |
|---|---|---|---|
| `page` | entier ≥ 1 | 1 | Page |
| `limit` | entier, 1 à 100 | 20 | Taille de page |
| `partnerWid`, `partnerId` | WID ou UUID | — | Restreint à un propriétaire |

```bash
curl -s "https://api.wakastart.app/api/config/networks?limit=20" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

**Réponse `200`**

```json
{
  "data": [
    {
      "id": "b2c4e6f8-1a3b-4c5d-8e9f-0a1b2c3d4e5f",
      "wid": "EXNET1",
      "appId": "a1b2c3d4-0000-4000-8000-000000000001",
      "name": "Réseau Exemple",
      "description": null,
      "subdomain": "reseau-exemple",
      "status": "ACTIVE",
      "createdAt": "2026-02-10T09:00:00.000Z",
      "updatedAt": "2026-09-01T14:30:00.000Z"
    }
  ],
  "meta": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 }
}
```

## Lire un réseau

::endpoint{method="GET" path="/api/config/networks/{wid}"}

**Droit requis** : `networks.read`. `wid` : identifiant court du réseau. Réponse : l'objet Réseau.

**Erreurs** : `403` `Network not found or not accessible`, `403` `Network not in caller scope`, `404` `Network with WID <wid> not found`.

## Créer un réseau

::endpoint{method="POST" path="/api/config/networks"}

**Droit requis** : `networks.create`. Réservé aux administrateurs réseau et aux propriétaires de l'application.

| Champ | Type | Obligatoire | Contraintes |
|---|---|---|---|
| `appId` | UUID | oui | Application du réseau |
| `name` | chaîne | oui | 100 caractères au plus |
| `description` | chaîne | non | 250 caractères au plus |
| `subdomain` | chaîne | non | 15 caractères au plus, `^[a-z0-9-]+$` |
| `defLangId`, `defThemeId` | UUID | non | Langue et thème par défaut |
| `status` | chaîne | non | Défaut `ACTIVE` |

```bash
curl -s -X POST https://api.wakastart.app/api/config/networks \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "appId": "a1b2c3d4-0000-4000-8000-000000000001",
    "name": "Réseau Sud",
    "subdomain": "reseau-sud"
  }'
```

**Réponse `201`** : l'objet Réseau créé. Wakastart provisionne ensuite le realm Keycloak du réseau dans chaque environnement.

**Erreurs** : `400` `Application avec ID <id> non trouvée` ; `409` `La valeur du champ "subdomain" existe déjà. Veuillez en choisir une autre.`

## Modifier un réseau

::endpoint{method="PUT" path="/api/config/networks/{wid}"}

**Droit requis** : `networks.update`. Tous les champs de la création sont facultatifs, sauf `appId`, qui ne peut pas être modifié. Réponse : l'objet Réseau modifié.

## Lister les clients

::endpoint{method="GET" path="/api/config/customers"}

**Droit requis** : `customers.read`.

| Paramètre de requête | Type | Défaut | Description |
|---|---|---|---|
| `page` | entier ≥ 1 | 1 | Page |
| `limit` | entier, 1 à 100 | 20 | Taille de page |
| `networkWid`, `networkId` | WID ou UUID | — | Restreint à un réseau |

```bash
curl -s "https://api.wakastart.app/api/config/customers?networkWid=EXNET1" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

**Réponse `200`**

```json
{
  "data": [
    {
      "id": "c3d5e7f9-2b4c-4d6e-9f0a-1b2c3d4e5f60",
      "wid": "EXCLI1",
      "networkId": "b2c4e6f8-1a3b-4c5d-8e9f-0a1b2c3d4e5f",
      "name": "Clinique Exemple",
      "description": null,
      "subdomain": null,
      "entityId": "d4e6f8a0-3c5d-4e7f-8a1b-2c3d4e5f6a70",
      "allowAutoRegistration": false,
      "status": "ACTIVE",
      "createdAt": "2026-03-01T08:00:00.000Z",
      "updatedAt": "2026-03-01T08:00:00.000Z"
    }
  ],
  "meta": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 }
}
```

## Lire un client

::endpoint{method="GET" path="/api/config/customers/{wid}"}

**Droit requis** : `customers.read`. Réponse : l'objet Client.

**Erreurs** : `403` `Accès refusé à ce customer` ; `404` `Customer with WID <wid> not found`.

## Créer un client

::endpoint{method="POST" path="/api/config/customers"}

**Droit requis** : `customers.create`. Réservé aux administrateurs réseau et aux propriétaires de l'application.

| Champ | Type | Obligatoire | Contraintes |
|---|---|---|---|
| `networkId` | UUID | oui | Réseau du client |
| `name` | chaîne | oui | 100 caractères au plus |
| `entityId` | UUID | oui | Entité juridique du client, créée au préalable dans la console |
| `description` | chaîne | non | 250 caractères au plus |
| `subdomain` | chaîne | non | 15 caractères au plus, `^[a-z0-9-]+$` |
| `defLangId`, `defThemeId` | UUID | non | Langue et thème par défaut |
| `status` | chaîne | non | Défaut `ACTIVE`. Sa modification dépend du niveau de l'appelant |

```bash
curl -s -X POST https://api.wakastart.app/api/config/customers \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "networkId": "b2c4e6f8-1a3b-4c5d-8e9f-0a1b2c3d4e5f",
    "name": "Cabinet Exemple",
    "entityId": "d4e6f8a0-3c5d-4e7f-8a1b-2c3d4e5f6a70"
  }'
```

**Réponse `201`** : l'objet Client créé. Wakastart crée en même temps l'organisation Keycloak du client dans le realm du réseau.

**Erreurs**

| Statut | Message |
|---|---|
| `403` | `Niveau d'administration insuffisant pour créer un customer` |
| `404` | `Network with ID <id> not found` |
| `404` | `Network <nom> has no realm configured` |
| `409` | `La valeur du champ "<champ>" existe déjà. Veuillez en choisir une autre.` |
| `500` | `Échec de la création de l'organisation dans Keycloak: <détail>` |

## Modifier un client

::endpoint{method="PUT" path="/api/config/customers/{wid}"}

**Droit requis** : `customers.update`. Tous les champs de la création sont facultatifs, sauf `networkId`, qui ne peut pas être modifié.

```bash
curl -s -X PUT https://api.wakastart.app/api/config/customers/EXCLI1 \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{ "name": "Clinique Exemple Nord" }'
```

Réponse : l'objet Client modifié.

## Supprimer un client

::endpoint{method="DELETE" path="/api/config/customers/{wid}"}

**Droit requis** : `customers.delete`. Réservé aux administrateurs réseau et aux propriétaires de l'application. Retirez d'abord les utilisateurs, les équipes et les fournisseurs d'identité du client.

**Erreurs** : `409` `Impossible de supprimer ce client car il possède encore des utilisateurs…`, ou des équipes, ou des fournisseurs d'identité.
