# Autenticación

Cómo se autentican las solicitudes: la cabecera X-API-Key, de dónde salen las claves y qué ocurre cuando falta una o es incorrecta.

Cada solicitud a la API de PDF Blocks se autentica con una clave de API
secreta enviada en la cabecera `X-API-Key`, por HTTPS. No hay tokens que
intercambiar ni sesiones que gestionar: una cabecera en cada llamada.

## La cabecera X-API-Key

Envíe su clave en la cabecera `X-API-Key` (con estas mayúsculas exactas). El
documento va en el cuerpo `multipart/form-data` como de costumbre:

```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
```

Una misma clave funciona en todas las regiones: solo cambia la URL base.
Consulte [Regiones y residencia de
datos](/docs/api/regions-and-data-residency) para ver la lista completa de
endpoints.

## Obtenga una clave de API

Cree y gestione sus claves desde el
[dashboard](https://dashboard.pdfblocks.com). Una clave se muestra completa
una sola vez, al crearla, así que cópiela en un lugar seguro. Trátela como
una contraseña: cualquiera que la tenga puede hacer solicitudes que se
facturan a su cuenta.

## Solo HTTPS

<Warning>
  La API se sirve solo por HTTPS. Las solicitudes a `http://` se rechazan y
  su clave nunca debe viajar por una conexión sin cifrar. Llame siempre a la
  URL base `https://`.
</Warning>

## Mantenga las claves fuera del control de versiones

Nunca escriba una clave directamente en el código ni la suba a un
repositorio. Léala en tiempo de ejecución desde una variable de entorno o un
gestor de secretos:

```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
```

Rote sus claves periódicamente y siempre que una haya podido quedar expuesta.
Cree la sustituta en el [dashboard](https://dashboard.pdfblocks.com),
despliéguela y después borre la antigua: como la clave se envía en cada
solicitud, rotarla es solo un cambio de configuración, sin código que
reescribir. Emita una clave distinta por aplicación para poder revocar una
sin afectar a las demás.

## Cuando falla la autenticación

Una clave ausente, mal formada o no válida devuelve `401 Unauthorized` con un
cuerpo `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
}
```

Compruebe que el nombre de la cabecera es exactamente `X-API-Key`, que el
valor es la clave completa y que está llamando a una URL `https://`. Consulte
[Errores](/docs/api/errors) para ver todos los códigos de estado y la forma
completa de la respuesta.