# Authentication
How requests are authenticated: the X-API-Key header, where keys come from, and what happens when one is missing or wrong.
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.
How requests are authenticated: the X-API-Key header, where keys come from, and what happens when one is missing or wrong.
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.
Create and manage keys from the dashboard. 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.
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.
Rotate keys periodically and whenever one may have been exposed. Create the
replacement in the dashboard, 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.
A missing, malformed, or invalid key returns 401 Unauthorized as an
application/problem+json body:
{ "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 for
every status code and the full response shape.
