API 認証

Zenovay API は API 認証情報を使用して認証します。すべての API リクエストに有効な認証情報を含める必要があります。

個人トークンとワークスペースキー

Zenovay には 2 つの種類の API 認証情報があります。どちらも同じ方法で認証されます（以下を参照）。ただし、所有者と有効期限が異なります。

個人用 API トークン は、属しているチーム全体であなたに代わって機能します。Settings → Account → Security & access で作成します。独自のアクセス権を持ち、スコープを設定することができ（スコープを参照）、チームを離れると自動的に取り消されます。独自のスクリプト、CLI、またはローカル開発用に使用します。

ワークスペース API キー はユーザーではなく、ワークスペースに属します。オーナーと管理者は Settings → Security → API keys で作成および管理します。メンバーの変更の影響を受けないため、共有統合と CI に適しています。ワークスペースキーは完全なアクセス権を持つか、単一の Web サイトに限定できます。

API キーの取得

1. Zenovay ダッシュボードにログインします
2. Settings → Security → API keys に移動します
3. Create New API Key をクリックします
4. キーにわかりやすい名前を付けます
5. 生成されたキーをコピーします（1 回のみ表示されます）

API キーの使用

すべてのリクエストの X-API-Key ヘッダーに API キーを含めます：

curl -X GET "https://api.zenovay.com/api/external/v1/websites" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json"

Bearer トークン認証

X-API-Key ヘッダーの代わりに、標準的な Authorization: Bearer ヘッダーを使用して認証できます：

curl -X GET "https://api.zenovay.com/api/external/v1/websites" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json"

どちらの方法も同じ API キーを使用します。アプリケーションまたは HTTP クライアントに最適な方法を選択してください。

JavaScript の例

const apiKey = process.env.ZENOVAY_API_KEY;

const response = await fetch('https://api.zenovay.com/api/external/v1/websites', {
headers: {
  'X-API-Key': apiKey,
  'Content-Type': 'application/json'
}
});

const data = await response.json();

スコープ

認証情報は異なる権限レベルを持つことができます：

full_access - デフォルト。認証情報所有者ができるすべてのこと
read - 分析データと Web サイト設定を表示
write - Web サイト設定を変更
admin - 管理アクションを含む昇格されたアクセス

個人用トークンの場合、admin スコープはすでにオーナーまたは管理者であるチームにのみ付与されます。管理者ではないチームをカバーするトークンは、admin スコープで作成することはできません。

レート制限

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

• 決して API キーをバージョン管理にコミットしないでください
• 環境変数を使用してキーを保管します
• キーを定期的にローテーションします
• 異なる環境（開発、ステージング、本番）用に別々のキーを作成します
• 未使用のキーはすぐに削除します

一般的なエラー