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

# API REST d'administration

> La surface REST opérationnelle /admin/v1 : l'authentification, la carte des points d'accès (comptes, organisations, bannissements, file, spam, configuration, version), et où l'administration en JMAP prend le relais.

L'API REST sous `/admin/v1` est la surface **opérationnelle** : les points d'accès que les scripts et la supervision appellent. Vérification de déploiement, bannissements, file, surcharges de configuration. Les objets d'administration de *données* (organisations, journal d'audit, règles de journalisation, gestion des principals d'administration) vivent sur **l'administration en JMAP** (`urn:oximail:params:jmap:v2:admin`, ADR-075) : les nouveaux objets d'administration s'y ajoutent, pas ici.

## Authentification

Chaque point d'accès exige le token bearer d'administration de `[admin] token` :

```bash theme={null}
curl -H "Authorization: Bearer $ADMIN_TOKEN" https://mail.example.com/admin/v1/version
```

Liez la surface d'administration à un port local séparé avec `[server] admin_bind` si vous la préférez hors de l'écouteur public.

## Carte des points d'accès

### Déploiement & santé

| Point d'accès                | Rôle                                                                      |
| ---------------------------- | ------------------------------------------------------------------------- |
| `GET /admin/v1/version`      | La version et `migrations_applied` : la vérification d'après déploiement. |
| `GET /admin/v1/stats`        | Les statistiques de l'instance.                                           |
| `GET /admin/v1/logs/summary` | Un résumé agrégé des journaux récents.                                    |
| `GET /metrics`               | Les métriques Prometheus ([exploitation](../operator/operations)).        |

### Comptes et organisations

| Point d'accès                                                                                                                        | Rôle                                                                                                                         |
| ------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| `GET/POST /admin/v1/accounts`, `POST .../batch`                                                                                      | Lister et provisionner les comptes.                                                                                          |
| `GET/PUT/DELETE /admin/v1/accounts/{id}`                                                                                             | Inspecter, mettre à jour, supprimer (la suppression met en file la [machine à phases d'effacement](../operator/compliance)). |
| `POST .../{id}/enable`, `.../disable`, `PUT .../{id}/role`                                                                           | Cycle de vie et rôle.                                                                                                        |
| `GET .../{id}/capabilities`                                                                                                          | L'ensemble de capacités effectif.                                                                                            |
| `GET .../{id}/mailboxes`, `emails`, `identities`, `sieve` (+`/{name}/activate`), `calendars`, `events`, `contacts`, `tasks`, `files` | Les vues de données par compte pour l'outillage de support.                                                                  |
| `GET/POST /admin/v1/tenants`, `GET/PUT /admin/v1/tenants/{id}`                                                                       | Les organisations.                                                                                                           |
| `PUT .../{id}/branding`, `.../{id}/plan`, `GET .../{id}/capabilities`, `.../capabilities-matrix`                                     | La marque, le plan et les interrupteurs de capacités par organisation.                                                       |

### Sécurité

| Point d'accès                                             | Rôle                                            |
| --------------------------------------------------------- | ----------------------------------------------- |
| `GET/DELETE /admin/v1/bans`, `DELETE /admin/v1/bans/{ip}` | La liste des bannissements du fail2ban intégré. |
| `GET/POST/DELETE /admin/v1/whitelist(/{ip})`              | La liste blanche de confiance.                  |

### Opérations courrier

| Point d'accès                                                                                                                                    | Rôle                                                                   |
| ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- |
| `GET /admin/v1/queue`, `GET/DELETE .../{id}`, `POST .../{id}/retry`, `POST .../flush`                                                            | La file de remise sortante.                                            |
| `GET /admin/v1/spam/stats`, `POST .../test`, `POST .../feedback/{tenant}`, `POST .../retrain/{tenant}`, `GET/PUT .../blocklist`, `GET .../model` | Le corpus et le modèle du [pipeline anti-spam](../operator/anti-spam). |
| `POST /admin/v1/reindex-blobs`                                                                                                                   | La maintenance de réindexation liée aux blobs.                         |

### Configuration

| Point d'accès          | Rôle                                                                                                                                                                                                       |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PUT /admin/v1/config` | Poser des surcharges de configuration à l'exécution (`{"overrides": {"clé": valeur}}`) : voir [configuration](../operator/configuration). En v0.30.0, `GET` renvoie une indication d'usage, pas un export. |

## Conventions

* Les réponses sont en JSON ; les erreurs portent une raison lisible par machine et un statut HTTP qui dit ce qu'il veut dire.
* Tout ce qui est ici est aussi accessible par la [CLI](../operator/cli) : les deux sont des adaptateurs minces au-dessus de la même orchestration, le comportement est identique.
* L'API est **par organisation** partout où les données le sont ; il n'existe volontairement pas de vue de données inter-organisations.