APIキーの管理
概要
APIキーは、DocMap APIへのプログラムアクセスを提供します。各キーは72文字のトークンで、dm_live_ プレフィックスが付き、Authorization ヘッダーでBearerトークンとして渡します。
基本情報：
- アカウントあたり最大 10個のアクティブキー
- 形式:
dm_live_の後に64文字のランダムな16進数文字（合計72文字） - キーは保存前にハッシュ化されます -- 生のキーは作成時に 一度だけ 表示されます
- キーには有効期限を設定するか、無期限に設定できます
キーの作成
ダッシュボードから
- DocMapダッシュボードの 設定 > APIキー に移動します
- APIキーを作成 をクリックします
- わかりやすい名前を入力します（例：「本番サーバー」、「CI/CDパイプライン」）
- 有効期限を選択します
- 表示されたキーをすぐにコピーしてください -- 再度表示されることはありません
APIから
既存のAPIキーで認証して、プログラムからキーを作成することもできます：
curl -X POST https://api.docmap.io/v1/api-keys \
-H "Authorization: Bearer dm_live_your_existing_api_key" \
-H "Content-Type: application/json" \
-d '{
"name": "Production Server",
"expiresIn": "90d"
}'const response = await fetch("https://api.docmap.io/v1/api-keys", {
method: "POST",
headers: {
Authorization: `Bearer ${existingApiKey}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
name: "Production Server",
expiresIn: "90d",
}),
});
const { data } = await response.json();
// すぐに保存してください -- 再度表示されることはありません
console.log("API Key:", data.key);
console.log("Key ID:", data.apiKey.id);import requests
response = requests.post(
"https://api.docmap.io/v1/api-keys",
headers={
"Authorization": f"Bearer {existing_api_key}",
"Content-Type": "application/json",
},
json={
"name": "Production Server",
"expiresIn": "90d",
},
)
data = response.json()["data"]
# すぐに保存してください -- 再度表示されることはありません
print("API Key:", data["key"])
print("Key ID:", data["apiKey"]["id"])利用可能な expiresIn の値：
| 値 | 期間 |
|---|---|
30d | 30日 |
60d | 60日 |
90d | 90日 |
1y | 1年 |
never | 無期限 |
レスポンスには、生のキーとキーのメタデータの両方が含まれます：
{
"data": {
"key": "dm_live_a1b2c3d4e5f6...",
"apiKey": {
"id": "key-abc123",
"userId": "user_789",
"name": "Production Server",
"prefix": "dm_live_a1b2c3d4",
"expiresAt": "2025-10-13T12:00:00.000Z",
"lastUsedAt": null,
"createdAt": "2025-07-15T12:00:00.000Z",
"revoked": false
}
}
}WARNING
レスポンスの key フィールドは、生のAPIキーが返される 唯一のタイミング です。安全な場所（例：環境変数、シークレットマネージャー）にすぐに保存してください。紛失した場合は、新しいキーを作成する必要があります。
キーの一覧表示
アカウントのすべてのアクティブ（無効化されていない）APIキーを取得します：
curl https://api.docmap.io/v1/api-keys \
-H "Authorization: Bearer dm_live_your_api_key"const response = await fetch("https://api.docmap.io/v1/api-keys", {
headers: { Authorization: `Bearer ${apiKey}` },
});
const { data } = await response.json();
data.forEach((key) => {
console.log(`${key.name} (${key.prefix}...) - Last used: ${key.lastUsedAt ?? "Never"}`);
});response = requests.get(
"https://api.docmap.io/v1/api-keys",
headers={"Authorization": f"Bearer {api_key}"},
)
for key in response.json()["data"]:
last_used = key["lastUsedAt"] or "Never"
print(f"{key['name']} ({key['prefix']}...) - Last used: {last_used}")レスポンスには各キーのメタデータが含まれますが、完全なキー値は含まれません -- prefix（先頭16文字）のみが表示されます：
{
"data": [
{
"id": "key-abc123",
"userId": "user_789",
"name": "Production Server",
"prefix": "dm_live_a1b2c3d4",
"expiresAt": "2025-10-13T12:00:00.000Z",
"lastUsedAt": "2025-07-15T14:30:00.000Z",
"createdAt": "2025-07-15T12:00:00.000Z",
"revoked": false
}
]
}キーのローテーション
ダウンタイムなしでAPIキーをローテーションするには、以下の手順に従います：
- 新しいキーを作成する -- 代替であることを示すわかりやすい名前を付けます
- システムを更新する -- 環境変数、シークレットマネージャー、CI/CDを新しいキーに切り替えます
- 確認する -- テストAPIコールを行い、新しいキーが正常に動作することを確認します
- 古いキーを無効化する -- すべてのシステムが更新された後に行います
// ステップ1: 新しいキーを作成
const createResponse = await fetch("https://api.docmap.io/v1/api-keys", {
method: "POST",
headers: {
Authorization: `Bearer ${currentApiKey}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
name: "Production Server (rotated 2025-07)",
expiresIn: "90d",
}),
});
const { data: newKeyData } = await createResponse.json();
const newKey = newKeyData.key;
// ステップ2: 新しいキーの動作を確認
const testResponse = await fetch("https://api.docmap.io/v1/usage", {
headers: { Authorization: `Bearer ${newKey}` },
});
if (testResponse.ok) {
console.log("New key verified. Update your environment variables now.");
// ステップ3: 古いキーを無効化（システム更新後）
// await fetch(`https://api.docmap.io/v1/api-keys/${oldKeyId}`, {
// method: "DELETE",
// headers: { Authorization: `Bearer ${newKey}` },
// });
}TIP
移行期間中は両方のキーをアクティブに保ちます。すべてのシステムが新しいキーを使用していることを確認した後にのみ、古いキーを無効化してください。
キーの無効化
キーIDを指定して DELETE リクエストを送信し、APIキーを無効化します。キーは即座に無効になります。
curl -X DELETE https://api.docmap.io/v1/api-keys/key-abc123 \
-H "Authorization: Bearer dm_live_your_api_key"const response = await fetch("https://api.docmap.io/v1/api-keys/key-abc123", {
method: "DELETE",
headers: { Authorization: `Bearer ${apiKey}` },
});
const result = await response.json();
console.log("Revoked:", result.success); // trueresponse = requests.delete(
"https://api.docmap.io/v1/api-keys/key-abc123",
headers={"Authorization": f"Bearer {api_key}"},
)
print("Revoked:", response.json()["success"]) # TrueWARNING
無効化は即時かつ永続的です。無効化されたキーを使用するすべてのリクエストは 401 UNAUTHORIZED エラーを受け取ります。無効化する前に、アクティブなシステムがそのキーに依存していないことを確認してください。
使用状況の監視
各APIキーは、キーがリクエストの認証に使用されるたびに自動的に更新される lastUsedAt タイムスタンプを追跡します。一覧エンドポイントを使用して、キーが最後にアクティブだった時期を監視します：
const response = await fetch("https://api.docmap.io/v1/api-keys", {
headers: { Authorization: `Bearer ${apiKey}` },
});
const { data: keys } = await response.json();
// 30日以上使用されていないキーを検索
const thirtyDaysAgo = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);
keys.forEach((key) => {
if (!key.lastUsedAt || new Date(key.lastUsedAt) < thirtyDaysAgo) {
console.log(`Key "${key.name}" (${key.prefix}...) is inactive — consider revoking it`);
}
});ベストプラクティス
わかりやすい名前を使用する。 キーには目的や環境に基づいて名前を付けます：「Production API」、「Staging」、「GitHub Actions CI」。これにより、漏洩した場合にどのキーを無効化すべきかを簡単に特定できます。
有効期限を設定する。
neverよりも90dや1yを推奨します。有効期限のあるキーは定期的なローテーションを強制し、キーが漏洩した場合の露出期間を制限します。環境を分離する。 開発、ステージング、本番環境で異なるキーを使用します。環境間でキーを共有しないでください。
定期的にローテーションする。 有効期限がある場合でも、特にチームメンバーの退職やインフラの変更後は、積極的にキーをローテーションしてください。
生のキーをログに記録しない。 アプリケーションログ、エラーレポート、コンソール出力にAPIキーを出力しないでください。ログ内でキーを参照する必要がある場合は
prefixフィールドを使用してください。環境変数を使用する。 キーは環境変数またはシークレットマネージャーに保存します。ソースコードにハードコードしたり、バージョン管理にコミットしたりしないでください。