# Authentification

Comment les requêtes sont authentifiées : l’en-tête X-API-Key, d’où viennent les clés et ce qui se passe quand elle manque ou qu’elle est erronée.

Chaque requête à l’API PDF Blocks est authentifiée par une clé d’API secrète
envoyée dans l’en-tête `X-API-Key`, en HTTPS. Il n’y a aucun jeton à échanger ni
aucune session à gérer : un en-tête sur chaque appel.

## L’en-tête X-API-Key

Envoyez votre clé dans l’en-tête `X-API-Key` (exactement cette casse). Le
document part dans le corps `multipart/form-data` comme d’habitude :

```bash title="cURL"
curl https://api.pdfblocks.com/v1/add_text_watermark \
  -H 'X-API-Key: your_api_key' \
  -F file=@input.pdf \
  -F line_1='CONFIDENTIAL' \
  -o watermarked.pdf
```

Une seule clé fonctionne sur toutes les régions : seule l’URL de base change.
Voir [Régions et résidence des données](/docs/api/regions-and-data-residency)
pour la liste complète des endpoints.

## Obtenir une clé d’API

Créez et gérez vos clés depuis le [dashboard](https://dashboard.pdfblocks.com).
Une clé n’est affichée en entier qu’une seule fois, à sa création : copiez-la en
lieu sûr. Traitez-la comme un mot de passe, car quiconque la détient peut faire
des requêtes facturées à votre compte.

## HTTPS uniquement

<Warning>
  L’API n’est servie qu’en HTTPS. Les requêtes vers `http://` sont refusées et
  votre clé ne doit jamais circuler sur une connexion non chiffrée. Appelez
  toujours l’URL de base en `https://`.
</Warning>

## Gardez les clés hors du contrôle de version

Ne codez jamais une clé en dur et ne la validez jamais dans un dépôt. Lisez-la
plutôt depuis une variable d’environnement ou un gestionnaire de secrets à
l’exécution :

```bash title="cURL"
export PDFBLOCKS_API_KEY='your_api_key'

curl https://api.pdfblocks.com/v1/add_text_watermark \
  -H "X-API-Key: $PDFBLOCKS_API_KEY" \
  -F file=@input.pdf \
  -F line_1='CONFIDENTIAL' \
  -o watermarked.pdf
```

Faites tourner vos clés régulièrement, et dès que l’une d’elles a pu être
exposée. Créez la remplaçante dans le
[dashboard](https://dashboard.pdfblocks.com), déployez-la, puis supprimez
l’ancienne : comme une clé est envoyée à chaque requête, une rotation n’est
qu’un changement de configuration, sans code à réécrire. Émettez une clé
distincte par application, afin de pouvoir en révoquer une sans perturber les
autres.

## Quand l’authentification échoue

Une clé absente, malformée ou invalide renvoie `401 Unauthorized` sous la forme
d’un corps `application/problem+json` :

```json
{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/401",
  "title": "The request is missing a valid API key.",
  "status": 401
}
```

Vérifiez que le nom de l’en-tête est exactement `X-API-Key`, que la valeur est la
clé complète et que vous appelez une URL en `https://`. Voir
[Erreurs](/docs/api/errors) pour tous les codes de statut et la forme complète de
la réponse.