---
title: Authentification et scopes
description: Présenter la clé dans l'en-tête Authorization et comprendre comment l'autorisation effective est calculée à chaque appel.
---

# Authentification et scopes

Chaque appel présente la clé dans l'en-tête `Authorization`. La plateforme vérifie la clé, puis recalcule vos droits à chaque requête, dans la même transaction que l'action demandée.

**Qui peut le faire** : tout outil qui détient une clé valide. Les actions possibles dépendent des droits de la clé et du rôle actuel de son propriétaire.

## Présenter la clé

```http
GET /api/v1/projects HTTP/1.1
Host: maintain.example
Authorization: Bearer 101m_<identifiant>.<secret>
```

Seul cet en-tête est accepté :

- un cookie de session du navigateur n'authentifie rien sur `/api/v1` ;
- une clé passée dans l'URL n'est jamais lue ;
- une clé mal formée, inconnue, expirée ou révoquée, ou celle d'un compte inactif, reçoit `401`.

La clé est vérifiée **avant** toute validation de paramètre et toute recherche de ressource. Sans clé valide, la réponse est `401` avec l'en-tête `WWW-Authenticate: Bearer realm="101maintain"`, que l'identifiant demandé existe, soit inconnu ou mal formé. Un appel non authentifié ne révèle donc rien.

Seule la route `GET /api/v1/openapi.json` reste publique.

## L'autorisation effective

Un appel est autorisé seulement si **toutes** les conditions suivantes sont vraies au moment de l'appel :

1. le compte propriétaire est actif ;
2. il a encore un rôle sur le projet, suffisant pour l'action (l'Administrateur voit tous les projets) ;
3. le projet est celui de la clé (et le dépôt visé lui appartient) ;
4. la clé détient le scope requis par la route ;
5. les règles métier du moment l'acceptent (dépôt actif et rattaché, issue ouverte, budgets…).

Aucun droit n'est figé à la création de la clé. Si votre rôle passe d'Opérateur à Lecteur, la clé ne peut plus démarrer d'exécution, même si elle porte encore le scope `runs:create`.

## Scopes et rôle minimal

| Scope | Routes | Rôle minimal |
| --- | --- | --- |
| `projects:read` | `GET /api/v1/projects` | Lecteur |
| `repositories:read` | `GET /api/v1/projects/<projectId>/repositories` | Lecteur |
| `runs:read` | `GET …/runs`, `GET /api/v1/runs/<runId>` | Lecteur |
| `runs:create` | `POST /api/v1/projects/<projectId>/runs` | Opérateur |
| `runs:cancel` | `POST /api/v1/runs/<runId>/cancel` | Opérateur |
| `audits:read` | `GET …/audits`, `GET /api/v1/audits/<auditId>` | Lecteur |
| `audits:create` | `POST /api/v1/projects/<projectId>/audits` | Opérateur |
| `reports:read` | `GET /api/v1/runs/<runId>/report`, `GET /api/v1/audits/<auditId>/report` | Lecteur |
| `usage:read` | `GET /api/v1/projects/<projectId>/usage` | Lecteur |

Le contrat OpenAPI indique le scope de chaque opération dans l'extension `x-required-scope`.

## 403 ou 404 ?

La plateforme distingue deux refus :

- **`404 not_found`** : la ressource n'existe pas **ou** elle est hors du périmètre de la clé. C'est le cas d'un projet non sélectionné, d'un projet que le propriétaire ne voit plus, d'un dépôt d'un autre projet ou d'une issue jamais reçue.
- **`403 forbidden`** : la ressource est visible, mais le scope manque ou le rôle actuel du propriétaire ne suffit pas.

Un outil ne doit donc jamais conclure d'un `404` qu'une ressource n'existe pas.

## Traçabilité

Chaque appel par clé est inscrit au journal des actions avec le type d'acteur « clé API », le compte propriétaire et la clé. Les refus de périmètre, de scope et de quota sont tracés aussi. Ni le secret, ni l'en-tête `Authorization`, ni le corps de la requête ne sont journalisés. La date de dernière utilisation de la clé est mise à jour à chaque appel avec une clé valide, même refusé.

Les traitements lancés par clé gardent la trace du propriétaire et de la clé. Le worker les recontrôle avant chaque étape : une clé révoquée ou expirée, un compte suspendu ou une adhésion perdue arrêtent la suite.

> [!NOTE]
> Une clé ne peut ni choisir une autre identité, ni accorder un droit, ni cocher une confirmation sensible. Un appel par clé ne prétend pas qu'une personne était présente.

## Pour continuer

Réessayez sans risque de doublon : [Idempotence, pagination et quotas](04-idempotence-et-quotas.md).
