---
title: Utilisateurs, Rôles & Invitations
excerpt: Gérer les utilisateurs du workspace, les rôles, les organisations et les invitations via l'API.
order: 6
---

Tous les endpoints de cette section sont **scopés au workspace** sauf indication contraire.

**En-têtes :** `Authorization: Bearer {token-workspace}`

---

## Utilisateurs

### GET /api/users

Retourne une liste paginée des utilisateurs du workspace. Supporte le filtrage et le tri.

**Paramètres de requête**

| Paramètre | Description |
|---|---|
| `filter[name]` | Filtrer par nom |
| `filter[email]` | Filtrer par email |
| `filter[phone]` | Filtrer par téléphone |
| `filter[term]` | Recherche plein texte |
| `sort` | Champ de tri : `id`, `name`, `email`, `created_at`, `updated_at`. Préfixer par `-` pour ordre décroissant (ex. `-created_at`) |
| `per_page` | Résultats par page (défaut : 20) |
| `page` | Numéro de page |

**Réponse `200`** : réponse paginée

```json
{
  "data": [
    {
      "id": 3,
      "name": "Bob Smith",
      "email": "bob@acme.com",
      "phone": "+33 1 00 00 00 00",
      "mobile_phone": null,
      "created_at": "2024-01-20T12:00:00Z",
      "updated_at": "2024-06-01T08:00:00Z"
    }
  ],
  "current_page": 1,
  "last_page": 1,
  "per_page": 20,
  "total": 1
}
```

---

### GET /api/users/{id}

Retourne un seul utilisateur. Requiert la permission groupe admin.

**Réponse `200`** : objet utilisateur

**Réponse `403`** : non autorisé

---

## Rôles

### GET /api/roles

Retourne tous les rôles définis dans le workspace. Requiert un utilisateur admin avec la permission `role.view` (également requise par `GET /api/roles/{id}`).

**Réponse `200`**

```json
[
  { "id": 1, "name": "manager", "permissions_count": 12 },
  { "id": 2, "name": "agent", "permissions_count": 5 }
]
```

---

### GET /api/roles/{id}

Retourne un seul rôle avec sa liste complète de permissions.

**Réponse `200`**

```json
{
  "permissions": ["customer.view", "customer.create", "customer.edit", ...],
  "id": 1,
  "team_id": 0,
  "name": "manager",
  "guard_name": "api",
  "created_at": "2024-01-10T08:00:00.000000Z",
  "updated_at": "2024-01-10T08:00:00.000000Z"
}
```

---

## Organisations

### GET /api/organisations

Retourne toutes les organisations du workspace (les entités juridiques qui le détiennent), sous forme de tableau JSON simple.

**Réponse `200`** : tableau d'objets organisation

```json
{
  "id": 1,
  "global_id": "b7f6c1d2-3e4a-4f5b-9c8d-0a1b2c3d4e5f",
  "tenant_id": "1b6feca6-cb4b-455e-a742-29e165e7446a",
  "name": "Acme Corp",
  "registration_number": "12345678900012",
  "tax_registration_number": "FR12345678900",
  "main_address_line_1": "10 rue de la Paix",
  "main_address_line_2": null,
  "main_address_post_code": "75002",
  "main_address_city": "Paris",
  "main_address_country": "France",
  "website": "https://acme.com",
  "created_at": "2024-01-10T08:00:00.000000Z",
  "updated_at": "2024-01-10T08:00:00.000000Z"
}
```

---

### GET /api/organisations/{id}

Retourne une seule organisation par son ID.

**Réponse `200`** : objet organisation

---

### PUT /api/organisations/{id}

Met à jour les détails d'une organisation. Le corps doit être un objet JSON ; seuls les champs envoyés sont modifiés.

Requiert un utilisateur admin avec la permission `organisation.edit`.

**Corps de la requête**

| Champ | Type | Requis | Description |
|---|---|---|---|
| `name` | string | non | Raison sociale (2 à 255 caractères) |
| `registration_number` | string | non | Numéro d'immatriculation |
| `tax_registration_number` | string | non | Numéro de TVA |
| `main_address_line_1` | string | non | Ligne d'adresse 1 |
| `main_address_line_2` | string | non | Ligne d'adresse 2 |
| `main_address_post_code` | string | non | Code postal |
| `main_address_city` | string | non | Ville |
| `main_address_country` | string | non | Pays |
| `website` | string | non | Site web |

`id`, `global_id`, `tenant_id`, `created_at` et `updated_at` ne peuvent pas être définis.

**Réponse `201`** : objet organisation mis à jour

**Réponse `403`** : l'utilisateur n'est pas admin ou n'a pas la permission `organisation.edit`

---

## Invitations utilisateurs

Les invitations sont gérées depuis l'**API centrale** (envoi vers le domaine central) pour les actions inter-workspace, ou depuis l'API workspace pour la gestion au niveau du workspace.

### GET /api/user-invites *(workspace)*

Liste toutes les invitations en attente dans le workspace.

**Réponse `200`** : tableau d'objets invitation

---

### POST /api/user-invites *(workspace)*

Envoie une invitation à un utilisateur pour rejoindre le workspace.

**Corps de la requête**

| Champ | Type | Requis | Description |
|---|---|---|---|
| `email` | string | oui | Adresse email de l'invité |
| `group` | string | oui | Groupe utilisateur : `admin` ou `user` |
| `role` | string | oui | Nom du rôle (doit exister dans le workspace) |
| `customer_id` | integer | oui (si group=user) | Client auquel l'utilisateur sera lié |

**Réponse `201`**

```json
{
  "id": 8,
  "group": "user",
  "email": "nouvelutilisateur@exemple.com",
  "role": "agent",
  "customer_id": 12
}
```

**Réponse `403`** : impossible de créer des invitations admin sans la permission requise

---

### DELETE /api/user-invites/{id} *(workspace)*

Annule une invitation en attente.

**Réponse `200`**

```json
{ "response": "element deleted" }
```

---

### GET /api/user-invites/pending *(central)*

Retourne toutes les invitations en attente envoyées à l'email de l'utilisateur authentifié, tous workspaces confondus. Utilisez cet endpoint sur le **domaine central**.

**En-têtes :** `Authorization: Bearer {token-central}`

**Réponse `200`** : tableau d'objets invitation (token visible)

---

### GET /api/user-invites/{token}/inspect *(central, non authentifié)*

Récupère les informations publiques d'une invitation spécifique sans nécessiter d'authentification. Utile pour pré-remplir les formulaires d'inscription ou de connexion.

**Réponse `200`**

```json
{
  "invite": { "id": 8, "email": "nouvelutilisateur@exemple.com", "group": "user" },
  "workspace": { "name": "Acme Corp" },
  "exists": false
}
```

**Réponse `400`** : invitation expirée ou plus en attente

---

### POST /api/user-invites/{token}/accept *(central)*

Accepte une invitation. L'utilisateur authentifié est ajouté au workspace avec le rôle invité.

**En-têtes :** `Authorization: Bearer {token-central}`

**Réponse `200`**

```json
{
  "message": "You have been successfully added to the workspace.",
  "workspace": { ... }
}
```

---

### POST /api/user-invites/{token}/decline *(central)*

Décline une invitation.

**En-têtes :** `Authorization: Bearer {token-central}`

**Réponse `200`**

```json
{ "response": "invite declined" }
```