# Autenticação

Como as requisições são autenticadas: o cabeçalho X-API-Key, de onde vêm as chaves e o que acontece quando uma delas falta ou está errada.

Toda requisição para a API do PDF Blocks é autenticada com uma chave de API
secreta enviada no cabeçalho `X-API-Key`, por HTTPS. Não há tokens para trocar
nem sessões para gerenciar: um cabeçalho em cada chamada.

## O cabeçalho X-API-Key

Envie sua chave no cabeçalho `X-API-Key` (exatamente com essas maiúsculas). O
documento vai no corpo `multipart/form-data`, como de costume:

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

Uma única chave funciona em todas as regiões: só a URL base muda. Consulte
[Regiões e residência de dados](/docs/api/regions-and-data-residency) para ver a
lista completa de endpoints.

## Obter uma chave de API

Crie e gerencie chaves no [dashboard](https://dashboard.pdfblocks.com). Uma chave
é exibida por inteiro apenas uma vez, quando você a cria, então copie-a para um
lugar seguro. Trate-a como uma senha: quem estiver com ela pode fazer requisições
cobradas da sua conta.

## Somente HTTPS

<Warning>
  A API é servida somente por HTTPS. Requisições para `http://` são recusadas, e
  sua chave nunca deve trafegar por uma conexão sem criptografia. Chame sempre a
  URL base `https://`.
</Warning>

## Mantenha as chaves fora do controle de versão

Nunca deixe uma chave fixa no código nem a envie para um repositório. Leia-a de
uma variável de ambiente ou de um gerenciador de segredos em tempo de execução:

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

Gire as chaves periodicamente e sempre que uma delas puder ter sido exposta. Crie
a substituta no [dashboard](https://dashboard.pdfblocks.com), implante-a e só
então exclua a chave antiga: como a chave é enviada em toda requisição, a rotação
é apenas uma mudança de configuração, sem código para reescrever. Emita uma chave
separada por aplicação para poder revogar uma sem atrapalhar as outras.

## Quando a autenticação falha

Uma chave ausente, malformada ou inválida retorna `401 Unauthorized` como um
corpo `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
}
```

Verifique se o nome do cabeçalho é exatamente `X-API-Key`, se o valor é a chave
completa e se você está chamando uma URL `https://`. Consulte
[Erros](/docs/api/errors) para ver todos os códigos de status e o formato
completo da resposta.