# Authentification

Chaque requête est authentifiée avec une seule **clé API**. Vous l’envoyez comme en-tête
`X-API-Key` — pas de valse OAuth, pas d’échange de jetons.
**Portée d’une clé API:** Une clé API donne accès uniquement au **service de téléversement de PDF** — les endpoints
`/api/v1/upload-service/*` (téléverser, statut de la tâche, télécharger, supprimer). C’est
toute la surface de traitement publique.

## Créer une clé API

La manière habituelle d’obtenir une clé est le **portail Accessful** : connectez-vous, ouvrez
**Clés API** et créez-en une. La clé n’est affichée **qu’une seule fois** à la création —
copiez-la immédiatement. Nous n’en stockons qu’un hachage, nous ne pourrons donc jamais la
réafficher.

Une clé ressemble à ceci :

```
ak_oCe4cm015zL8vCbBne_wUZDcM6G1RWqD7Ekc2944EAA
```

- Préfixe `ak_` suivi de 43 caractères compatibles avec les URL.
- Vous pouvez détenir jusqu’à **10 clés actives** par compte.
- Une clé peut éventuellement porter une **date d’expiration** ; révoquez-la à tout moment depuis le portail.
**Caution:** Traitez la clé comme un mot de passe. Elle est liée à votre compte et peut téléverser,
télécharger et **supprimer définitivement** vos cas. Ne l’intégrez jamais dans du code client
que vous distribuez aux utilisateurs finaux.

### Gérer les clés par programmation (facultatif)

Si vous automatisez la rotation des clés, les endpoints de gestion se trouvent sous
`/api/v1/auth/api-keys` et nécessitent un **jeton bearer OAuth2** issu de votre connexion au
portail (`Authorization: Bearer <jwt>`) — pas une clé API :

| Méthode &amp; chemin | Objet |
| --- | --- |
| `POST /api/v1/auth/api-keys` | Créer une clé — la réponse contient le texte en clair **une seule fois** |
| `GET /api/v1/auth/api-keys` | Lister vos clés (valeurs masquées) |
| `POST /api/v1/auth/api-keys/{id}/revoke` | Révoquer une clé |
| `DELETE /api/v1/auth/api-keys/{id}` | Supprimer une clé |

## Envoyer la clé sur les requêtes

Ajoutez l’en-tête `X-API-Key` à chaque appel :

```bash
curl https://api.accessful.de/api/v1/upload-service/job-status/<caseId> \
  -H "X-API-Key: ak_votre_cle_ici"
```
```js
await fetch(`https://api.accessful.de/api/v1/upload-service/job-status/${caseId}`, {
  headers: { 'X-API-Key': process.env.ACCESSFUL_API_KEY },
});
```
```java
HttpRequest.newBuilder()
    .uri(URI.create("https://api.accessful.de/api/v1/upload-service/job-status/" + caseId))
    .header("X-API-Key", System.getenv("ACCESSFUL_API_KEY"))
    .GET().build();
```
## Vérifier votre clé

Faites un test rapide en demandant un cas aléatoire et inexistant. Une clé qui fonctionne
renvoie **404** (le cas n’existe pas) — *et non* 401.

1. Envoyez une requête de statut avec un ID de cas jetable :

   ```bash
   curl -i https://api.accessful.de/api/v1/upload-service/job-status/00000000-0000-0000-0000-000000000000 \
     -H "X-API-Key: ak_votre_cle_ici"
   ```

2. Lisez la ligne de statut :

   - **`404 Not Found`** → votre clé est acceptée. ✅
   - **`401 Unauthorized`** → la clé est manquante, mal formée ou révoquée.

## Erreurs d’authentification

| Statut | Signification |
| --- | --- |
| `401 Unauthorized` | Pas de clé, clé mal formée ou clé révoquée/expirée. |
| `403 Forbidden` | La clé est valide mais n’a pas la permission pour cette action. |

Une clé manquante ou non valide (**401**) est rejetée au niveau du **gateway**, avant que la
requête n’atteigne l’application — un 401 ne porte donc jamais de corps
[Problem Details](https://docs.accessful.de/fr/errors/). Fiez-vous au code de statut. Un **403** provient de l’application
elle-même et porte un corps Problem Details, comme les autres erreurs applicatives.