> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wethehivers.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rôles et permissions

> Matrice des rôles, scopes d'accès et règles de contrôle

# Rôles & permissions

THE HIVE distingue **quatre rôles** correspondant à quatre profils utilisateurs distincts. Chaque endpoint exige un ou plusieurs rôles spécifiques.

## Hiérarchie des rôles

```mermaid theme={null}
flowchart TD
    SA[SUPER_ADMIN] -->|hérite de| A[ADMIN]
    A -->|hérite pas de| R[RECRUTEUR]
    A -->|hérite pas de| C[CANDIDAT]
    R -->|rattaché à| E[Entreprise]
    C -->|soumet| CA[Candidature]
    CA -->|vers| O[Offre]
    O -->|publiée par| R

    style SA fill:#264194,color:#fff
    style A fill:#4A63B5,color:#fff
    style R fill:#7B8DCB,color:#fff
    style C fill:#B2BEE2,color:#000
```

## Matrice d'accès

| Ressource              | CANDIDAT | RECRUTEUR    | ADMIN | SUPER\_ADMIN |
| ---------------------- | -------- | ------------ | ----- | ------------ |
| Profil candidat propre | R/W      | –            | R/W   | R/W          |
| Profil candidat autre  | –        | R (vivier)   | R/W   | R/W          |
| Candidature propre     | R/W      | –            | R/W   | R/W          |
| Candidature reçue      | –        | R/W          | R     | R            |
| Offre (publique)       | R        | R            | R     | R            |
| Offre (brouillon)      | –        | R/W (propre) | R/W   | R/W          |
| Entreprise propre      | –        | R/W          | R/W   | R/W          |
| Entreprise autre       | R        | R            | R/W   | R/W          |
| Vivier                 | –        | R/W          | R     | R            |
| Blog (lecture)         | R        | R            | R     | R            |
| Blog (écriture)        | –        | –            | R/W   | R/W          |
| Données de référence   | R        | R            | R     | R/W          |
| Administration (tous)  | –        | –            | R/W   | R/W          |
| Gestion admins         | –        | –            | –     | R/W          |

*R = lecture, W = écriture, – = interdit*

## Cycle de vie des comptes

### Candidat

```mermaid theme={null}
stateDiagram-v2
    [*] --> PENDING_EMAIL: register
    PENDING_EMAIL --> ACTIVE: validate-email
    ACTIVE --> SUSPENDED: admin suspend
    SUSPENDED --> ACTIVE: admin reactivate
    ACTIVE --> DELETED: delete-account
    DELETED --> [*]
```

### Recruteur

```mermaid theme={null}
stateDiagram-v2
    [*] --> PENDING_EMAIL: register
    PENDING_EMAIL --> PENDING_APPROVAL: validate-email
    PENDING_APPROVAL --> ACTIVE: admin validate
    PENDING_APPROVAL --> REJECTED: admin reject
    REJECTED --> PENDING_APPROVAL: admin revalidate
    ACTIVE --> SUSPENDED: admin suspend
    SUSPENDED --> ACTIVE: admin reactivate
    ACTIVE --> [*]
```

## Décision d'autorisation

```mermaid theme={null}
flowchart LR
    REQ[Requête HTTP] --> AUTH{Authorization?}
    AUTH -->|absent| A401[401 Unauthorized]
    AUTH -->|présent| JWT{JWT valide?}
    JWT -->|non| A401
    JWT -->|oui| ROLE{Rôle requis?}
    ROLE -->|match| SCOPE{Scope ressource?}
    ROLE -->|mismatch| A403[403 Forbidden]
    SCOPE -->|propriétaire / admin| OK[200 OK]
    SCOPE -->|autre| A403
```

## Scopes spéciaux

<Info>
  Certains endpoints élargissent la règle de rôle avec un contrôle de propriété : un recruteur ne peut modifier que **ses propres offres**, un candidat que **ses propres candidatures**. Un admin peut tout.
</Info>

<Warning>
  Le rôle `SUPER_ADMIN` ne peut être attribué qu'en base via script d'administration. Aucun endpoint ne permet de promouvoir un admin en super-admin.
</Warning>

## Header requis

Tous les endpoints protégés exigent un header `Authorization: Bearer <token>`. Voir [Authentification](/authentication).

```http theme={null}
GET /v1/api/candidates/profile HTTP/1.1
Host: api.wethehivers.com
Authorization: Bearer eyJhbGc...
```