# 認証

リクエストがどのように認証されるかについて説明します。X-API-Key ヘッダー、キーの入手方法、キーが欠落または誤っている場合に何が起こるかを扱います。

PDF Blocks API へのすべてのリクエストは、HTTPS 経由で `X-API-Key` ヘッダーに送信される秘密の API キーによって認証されます。交換するトークンも、管理するセッションもありません。すべての呼び出しにヘッダーが1つ付くだけです。

## X-API-Key ヘッダー

キーは `X-API-Key` ヘッダー（この大文字・小文字の表記のまま）で送信します。ドキュメントはいつもどおり `multipart/form-data` のボディに含めます。

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

1つのキーがすべてのリージョンで機能します。変わるのはベース URL だけです。エンドポイントの完全な一覧については、[リージョンとデータレジデンシー](/docs/api/regions-and-data-residency)を参照してください。

## API キーを取得する

キーの作成と管理は、[ダッシュボード](https://dashboard.pdfblocks.com)から行います。キーが全体表示されるのは作成時の1回だけなので、安全な場所にコピーしてください。パスワードと同じように扱いましょう。キーを持つ人は誰でも、あなたのアカウントに課金されるリクエストを送信できてしまいます。

## HTTPS のみ

<Warning>
  この API は HTTPS でのみ提供されます。`http://` へのリクエストは拒否され、キーが暗号化されていない接続を通ることは決してあってはなりません。常に `https://` のベース URL を呼び出してください。
</Warning>

## キーをソース管理の外に保つ

キーをハードコードしたり、リポジトリにコミットしたりしないでください。代わりに、実行時に環境変数やシークレットマネージャーから読み込みます。

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

キーは定期的に、また漏えいした可能性があるときはその都度ローテーションしてください。[ダッシュボード](https://dashboard.pdfblocks.com)で新しいキーを作成し、デプロイしてから、古いキーを削除します。キーはすべてのリクエストで送信されるため、ローテーションはコードの書き換えを伴わない、単なる設定変更です。アプリケーションごとに別々のキーを発行しておけば、他のキーに影響を与えずに1つだけ無効化できます。

## 認証が失敗した場合

キーが欠落している、形式が不正である、または無効である場合、`401 Unauthorized` が `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
}
```

ヘッダー名が正確に `X-API-Key` であること、値が完全なキーであること、そして `https://` の URL を呼び出していることを確認してください。すべてのステータスコードと完全なレスポンス形式については、[エラー](/docs/api/errors)を参照してください。