認証

概要

すべての /v1/* エンドポイントは、Bearerトークンを使用した Authorization ヘッダーによる認証が必要です：

Authorization: Bearer <token>

APIキー

APIキーは、サーバーサイドおよびプログラムからの利用に推奨される認証方式です。長期間有効で管理が容易であり、外部SDKを必要としません。

APIキーの作成

APIキーは2つの方法で作成できます：

ダッシュボードから：

ダッシュボード > 設定 > APIキー に移動します。
APIキーを作成 をクリックします。
わかりやすい名前を入力し、有効期限を選択します。
キーをすぐにコピーしてください。

APIから：

bash

curl -X POST https://api.docmap.io/v1/api-keys \
  -H "Authorization: Bearer <existing-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Server",
    "expiresIn": "90d"
  }'

キーの形式

APIキーは以下の形式に従います：

dm_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

キーは72文字で、常に dm_live_ プレフィックスで始まります。

有効期限オプション

キーを作成する際、以下の有効期限から選択できます：

30日
60日
90日
1年
無期限（有効期限なし）

WARNING

無期限のキーは便利ですが、漏洩した場合のリスクが高くなります。ニーズに合った最短の有効期限を使用してください。

制限

各アカウントでは、最大 10個のアクティブなAPIキー を同時に保持できます。スロットを空けるには、未使用のキーを無効化してください。

リクエスト例

cURLTypeScript

bash

curl https://api.docmap.io/v1/extractions \
  -H "Authorization: Bearer dm_live_your_api_key"

typescript

const response = await fetch('https://api.docmap.io/v1/extractions', {
  headers: {
    'Authorization': `Bearer ${process.env.DOCMAP_API_KEY}`,
  },
})

エラーレスポンス

認証に失敗した場合、APIは 401 Unauthorized レスポンスを返します：

json

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired authentication token."
  }
}

一般的な原因：

Authorization ヘッダーの欠落
トークンの形式が不正（プレフィックスや形式が間違っている）
期限切れのAPIキー
無効化されたAPIキー

セキュリティのベストプラクティス

DANGER

APIキーをクライアントサイドのコード、公開リポジトリ、またはブラウザ環境で公開しないでください。APIキーはアカウントのAPIへのフルアクセスを付与するため、シークレットとして扱う必要があります。

API認証情報を安全に保つために、以下のガイドラインに従ってください：

環境変数にキーを保存する -- ソースコードにAPIキーをハードコードしないでください。環境変数またはシークレットマネージャーを使用してください。
bash
```
# .envファイル（コミットしないでください）
DOCMAP_API_KEY=dm_live_your_api_key
```
typescript
```
// 環境変数から読み取り
const apiKey = process.env.DOCMAP_API_KEY
```
定期的にキーをローテーションする -- 漏洩の疑いがなくても、定期的に新しいキーを作成し、古いキーを廃止してください。
漏洩したキーは直ちに無効化する -- キーが誤って公開された場合（例：公開リポジトリにコミットされた場合）、すぐに ダッシュボード > 設定 > APIキー で無効化し、代わりのキーを作成してください。
合理的な最短の有効期限を使用する -- 利便性とセキュリティのバランスを取った有効期限を選択してください。ほとんどの本番環境では、90日がデフォルトとして適切です。
環境ごとに異なるキーを使用する -- 開発、ステージング、本番環境で別々のキーを作成してください。これにより、1つのキーが漏洩した場合の影響範囲が限定され、ダウンタイムなしでキーをローテーションしやすくなります。
.env ファイルを .gitignore に追加する -- 環境ファイルがバージョン管理にコミットされないようにしてください。
gitignore
```
# .gitignore
.env
.env.local
.env.*.local
```

認証 ​

概要 ​

APIキー ​

APIキーの作成 ​

キーの形式 ​

有効期限オプション ​

制限 ​

リクエスト例 ​

エラーレスポンス ​

セキュリティのベストプラクティス ​

認証

概要