# Droits et profils

> Gérer le catalogue des droits applicatifs, les profils, la matrice de droits de chaque environnement et l'attribution des profils avec l'API publique.

Votre application déclare un catalogue de [droits applicatifs](/v1.0/glossaire#droit-applicatif), des codes de la forme `ressource.action`. Un [profil](/v1.0/glossaire#profil) regroupe des droits. Droits et profils existent dans les trois environnements ; seule la **matrice profils × droits** est propre à chacun : un même profil peut porter `invoices.delete` en `dev` et pas en `prod`. Une fiche utilisateur, qui appartient à un environnement, reçoit un profil ; ses droits arrivent dans `GET /api/me` et dans le contrôle des endpoints.

Un profil se désigne par son **WID** (`{profile}` dans les chemins de cette page, 5 ou 6 caractères), commun aux trois environnements. L'UUID reste accepté sur les mêmes routes, mais le WID est l'identifiant public : utilisez-le dans vos intégrations.

**Environnement de l'appelant** : les routes de droits et d'utilisateurs d'un profil lisent et écrivent la matrice et les fiches de l'environnement de l'appelant, déduit de sa session (claim `wenv`) ou de sa clé API. `env` et `envType` y sont refusés en `400` `Environment is deduced from the caller and cannot be provided`. Il n'existe ni copie ni promotion de la matrice d'un environnement vers un autre.

**Accès commun** : appelant de niveau Administrateur client (`CUSTOMER_ADMIN`) au minimum, avec le droit applicatif indiqué. La gestion du catalogue et des profils revient en pratique à l'équipe qui édite l'application.

## L'objet Droit applicatif

| Champ | Type | Description |
|---|---|---|
| `id` | UUID | Identifiant technique |
| `appId` | UUID | Application. Non modifiable |
| `code` | chaîne (1 à 50) | Code unique dans l'application, par convention `ressource.action` : `invoices.read` |
| `name` | chaîne (100) | Libellé affiché |
| `description` | chaîne ou `null` | Description |
| `category` | chaîne (50) ou `null` | Regroupement dans les écrans |
| `isSystem` | booléen | Droit système, non modifiable |

Une application compte **200 droits au plus**. Un droit existe dans les trois environnements : il ne peut pas être limité à certains.

## L'objet Profil

| Champ | Type | Description |
|---|---|---|
| `id` | UUID | Identifiant technique |
| `wid` | chaîne (5 ou 6) | Identifiant public, commun aux trois environnements |
| `appId` | UUID | Application du profil |
| `networkId`, `customerId` | UUID ou `null` | Renseignés seulement pour un ancien profil propre à un réseau ou à un client, historique. Ces profils ne se créent plus |
| `name` | chaîne (100) | Nom, unique dans l'application (sans tenir compte de la casse) |
| `description` | chaîne ou `null` | Description |
| `isSystem` | booléen | Profil système, non modifiable |

## Lister les droits d'une application

::endpoint{method="GET" path="/api/config/app-rights/by-app/{appWid}"}

**Droit requis** : `app-rights.read`.

```bash
curl -s https://api.wakastart.app/api/config/app-rights/by-app/EXAPP1 \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

**Réponse `200`**

```json
[
  {
    "id": "0a1b2c3d-1111-4a2b-8c3d-4e5f6a7b8c01",
    "appId": "a1b2c3d4-0000-4000-8000-000000000001",
    "code": "invoices.read",
    "name": "Voir les factures",
    "description": null,
    "category": "Facturation",
    "isSystem": false
  }
]
```

`GET /api/config/app-rights` (paginé) et `GET /api/config/app-rights/{id}` lisent le catalogue avec le même droit, `app-rights.read`.

## Créer un droit

::endpoint{method="POST" path="/api/config/app-rights"}

**Droit requis** : `app-rights.create`.

| Champ | Type | Obligatoire | Contraintes |
|---|---|---|---|
| `appId` | UUID | oui | Application |
| `code` | chaîne | oui | 1 à 50 caractères, unique dans l'application |
| `name` | chaîne | oui | 100 caractères au plus |
| `description` | chaîne | non | — |
| `category` | chaîne | non | 50 caractères au plus |

```bash
curl -s -X POST https://api.wakastart.app/api/config/app-rights \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "appId": "a1b2c3d4-0000-4000-8000-000000000001",
    "code": "invoices.delete",
    "name": "Supprimer une facture",
    "category": "Facturation"
  }'
```

**Réponse `201`** : l'objet Droit applicatif créé.

**Erreurs** : `409` `Maximum 200 rights allowed per app` ; `409` `Right with code '<code>' already exists for this app`.

Le champ `availableEnvs` a disparu de la création et de la modification d'un droit : s'il est encore envoyé, il est ignoré. Retirez-le de vos appels.

## Modifier ou supprimer un droit

::endpoint{method="PUT" path="/api/config/app-rights/{id}"}

**Droit requis** : `app-rights.update`. Tous les champs de la création sont facultatifs, sauf `appId`.

::endpoint{method="DELETE" path="/api/config/app-rights/{id}"}

**Droit requis** : `app-rights.delete`.

**Erreurs** : `403` `Les droits système ne peuvent pas être modifiés` (ou `supprimés`).

## Lister les profils

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

**Droit requis** : `profiles.read`. Pagination `page` et `limit` (1 à 100, défaut 20). `GET /api/config/profiles/{profile}` lit un profil.

Profils vus depuis un client ou un réseau :

| Endpoint | Renvoie |
|---|---|
| `GET /api/config/profiles/customer/{customerWid}/visible` | Profils attribuables aux utilisateurs de ce client : profils de l'application que son réseau ne masque pas |
| `GET /api/config/profiles/customer/{customerWid}` | Anciens profils propres à ce client, historiques. `?includeInherited=true` ajoute ceux de l'application et du réseau |
| `GET /api/config/profiles/network/{networkWid}/available` | Profils de l'application, avec leur statut masqué ou non pour ce réseau |
| `GET /api/config/profiles/network/{networkWid}` | Anciens profils propres à ce réseau, historiques |

```bash
curl -s https://api.wakastart.app/api/config/profiles/customer/EXCLI1/visible \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Créer un profil

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

**Droit requis** : `profiles.create`.

| Champ | Type | Obligatoire | Contraintes |
|---|---|---|---|
| `appId` | UUID | oui | Application |
| `name` | chaîne | oui | 100 caractères au plus, unique dans l'application |
| `description` | chaîne | non | — |

```bash
curl -s -X POST https://api.wakastart.app/api/config/profiles \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "appId": "a1b2c3d4-0000-4000-8000-000000000001",
    "name": "Comptable"
  }'
```

**Réponse `201`** : l'objet Profil créé, présent dans les trois environnements, sans droit. Réglez ensuite ses droits dans chaque environnement.

**Erreurs** : `409` `Un profil nommé "<nom>" existe déjà pour cette application`. Un profil appartient toujours à l'application : il n'existe pas de champ pour le rattacher à un réseau ou à un client. `availableEnvs` est ignoré s'il est encore envoyé.

## Modifier ou supprimer un profil

::endpoint{method="PUT" path="/api/config/profiles/{profile}"}

**Droit requis** : `profiles.update`. Champs facultatifs : `name`, `description`. Un renommage vers un nom déjà pris dans l'application répond `409`.

::endpoint{method="DELETE" path="/api/config/profiles/{profile}"}

**Droit requis** : `profiles.delete`. Le profil ne doit plus être attribué, dans aucun environnement.

**Erreurs** : `403` `Les profils système ne peuvent pas être modifiés` (ou `supprimés`) ; `409` `Impossible de supprimer ce profil car il est encore attribué à des utilisateurs…`.

## Lire les droits d'un profil

::endpoint{method="GET" path="/api/config/profiles/{profile}/rights"}

**Accès** : réservé aux administrateurs client, sans droit applicatif supplémentaire. Renvoie les droits du profil **dans l'environnement de l'appelant** uniquement.

```bash
curl -s https://api.wakastart.app/api/config/profiles/EXPRO2/rights \
  -H "x-api-key: sk_test_exemple"
```

**Réponse `200`**

```json
[
  {
    "profileId": "9b8a7c6d-2222-4e3f-9a0b-1c2d3e4f5a60",
    "appRightId": "0a1b2c3d-1111-4a2b-8c3d-4e5f6a7b8c01",
    "envType": "prod",
    "appRight": { "id": "0a1b2c3d-1111-4a2b-8c3d-4e5f6a7b8c01", "code": "invoices.read", "name": "Voir les factures" }
  }
]
```

`envType` est toujours l'environnement de l'appelant. Pour lire la matrice d'un autre environnement, appelez avec un jeton ou une clé de cet environnement.

## Ajouter ou retirer un droit

::endpoint{method="POST" path="/api/config/profiles/{profile}/rights/{rightId}"}

::endpoint{method="DELETE" path="/api/config/profiles/{profile}/rights/{rightId}"}

**Accès** : réservé aux administrateurs client, sans droit applicatif supplémentaire. `{rightId}` est l'UUID du droit. Aucun corps n'est attendu : le droit est ajouté ou retiré dans la matrice de l'environnement de l'appelant.

```bash
curl -s -X POST https://api.wakastart.app/api/config/profiles/EXPRO2/rights/0a1b2c3d-1111-4a2b-8c3d-4e5f6a7b8c01 \
  -H "x-api-key: sk_test_exemple"
```

**Réponse** : `201` pour l'ajout, `200` pour le retrait.

**Erreurs** : `400` paramètre d'environnement fourni ; `404` profil, droit ou association introuvable ; `409` droit déjà associé au profil dans cet environnement.

## Remplacer tous les droits d'un profil

::endpoint{method="PUT" path="/api/config/profiles/{profile}/rights"}

**Accès** : réservé aux administrateurs client, sans droit applicatif supplémentaire. Remplace l'ensemble des droits du profil **dans l'environnement de l'appelant** par la liste envoyée. Les deux autres environnements ne sont pas touchés.

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `entries` | tableau | oui | `{ "appRightId": UUID }`. Une liste vide retire tous les droits du profil dans cet environnement. Un `envType` dans une entrée est refusé (`400`) |

```bash
curl -s -X PUT https://api.wakastart.app/api/config/profiles/EXPRO2/rights \
  -H "x-api-key: sk_test_exemple" \
  -H 'Content-Type: application/json' \
  -d '{
    "entries": [
      { "appRightId": "0a1b2c3d-1111-4a2b-8c3d-4e5f6a7b8c01" },
      { "appRightId": "0a1b2c3d-1111-4a2b-8c3d-4e5f6a7b8c02" }
    ]
  }'
```

**Réponse `200`** : les droits du profil dans cet environnement.

Les droits ainsi modifiés s'appliquent aux prochains appels des utilisateurs concernés, en général dans la minute.

## Attribuer un profil à un utilisateur

::endpoint{method="GET" path="/api/config/profiles/{profile}/users"}

::endpoint{method="POST" path="/api/config/profiles/{profile}/users/{userWid}"}

::endpoint{method="DELETE" path="/api/config/profiles/{profile}/users/{userWid}"}

**Accès** : réservé aux administrateurs client, sans droit applicatif supplémentaire. `GET` liste les fiches de l'environnement de l'appelant qui portent ce profil. `POST` attribue le profil à une fiche de cet environnement, `DELETE` le lui retire ; `{userWid}` est le WID de la fiche dans l'environnement de l'appelant.

```bash
curl -s -X POST https://api.wakastart.app/api/config/profiles/EXPRO2/users/EXUSR5 \
  -H "x-api-key: sk_test_exemple"
```

**Réponse** : `201` et l'objet Utilisateur pour l'attribution ; `200` pour le retrait.

**Erreurs** : `404` profil ou fiche introuvable (dont le WID d'une fiche d'un autre environnement) ; `409` profil déjà attribué à cette fiche.
