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

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.

**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
{
  "id": 1,
  "name": "manager",
  "permissions_count": 12,
  "permissions": ["customer.view", "customer.create", "customer.update", ...]
}
```

---

## Organisations

### GET /api/organisations

Retourne toutes les organisations du workspace.

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

---

### 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.

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

---

## 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" }
```