# Authentication

Authenticate every request with your secret API key in the X-API-Key header, sent over HTTPS.

Every request to the PDF Blocks API is authenticated with a secret API key sent
in the `X-API-Key` header, over HTTPS. There are no tokens to exchange and no
sessions to manage — one header on every call.

## The X-API-Key header

Send your key in the `X-API-Key` header (this exact casing). The document goes in
the `multipart/form-data` body as usual:

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

One key works against every region — only the base URL changes. See
[Regions & data residency](/docs/api/regions-and-data-residency) for the full
list of endpoints.

## Get an API key

Create and manage keys from the [dashboard](https://dashboard.pdfblocks.com). A
key is shown in full only once, when you create it, so copy it somewhere safe.
Treat it like a password: anyone holding it can make requests billed to your
account.

## HTTPS only

<Warning>
  The API is served over HTTPS only. Requests to `http://` are refused, and your
  key must never travel over an unencrypted connection. Always call the
  `https://` base URL.
</Warning>

## Keep keys out of source control

Never hard-code a key or commit it to a repository. Read it from an environment
variable or a secret manager at runtime instead:

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

Rotate keys periodically and whenever one may have been exposed. Create the
replacement in the [dashboard](https://dashboard.pdfblocks.com), deploy it, then
delete the old key — because a key is sent on every request, rotation is just a
config change with no code to rewrite. Issue a separate key per application so
you can revoke one without disrupting the others.

## When authentication fails

A missing, malformed, or invalid key returns `401 Unauthorized` as an
`application/problem+json` body:

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

Check that the header name is exactly `X-API-Key`, that the value is the full key,
and that you are calling an `https://` URL. See [Errors](/docs/api/errors) for
every status code and the full response shape.