認証とAPIキー

Pro プラン

APIキーを使用してAPIアクセスを保護します。統合用のキーを作成・管理できます。

情報

Zenovay REST APIは有料機能です。APIキーを作成・使用するにはProプラン以上が必要です。無料チームはトラッキングスクリプトでイベントを送信できますが、プログラムAPI呼び出しはできません。

認証方法

APIキー（主要方法）

X-API-Keyヘッダー（推奨）またはAuthorization: Bearerヘッダーを使用して認証します：

curl https://api.zenovay.com/api/external/v1/websites \
  -H "X-API-Key: zv_YOUR_API_KEY"

またはBearerトークン認証の場合：

curl https://api.zenovay.com/api/external/v1/websites \
  -H "Authorization: Bearer zv_YOUR_API_KEY"

APIキーは常にzv_プレフィックスで始まります。

APIキーの作成

ZenovayのAPIキーは個人キーです：各リクエストはキーを作成したユーザーであるあなたに帰属します。

ステップ1：APIキーセクションを開く

設定 → アカウント → セキュリティ＆アクセス (/settings/account/security) に移動します
個人用APIキーカードを見つけます
新しいAPIキーをクリックします

設定 → アカウント → セキュリティ＆アクセスページ。既存のキーと新しいAPIキーボタンが表示された個人用APIキーカード — セキュリティ＆アクセスページは、個人用APIキーを作成・管理する場所です。

ステップ2：キーを設定

作成フォームでは3つのことを指定します：

┌─────────────────────────────────────────────────────┐
│ APIキーを作成                                       │
│ ─────────────────────────────────────────────────── │
│                                                     │
│ キー名                                              │
│ [ 本番統合                            ]             │
│                                                     │
│ 権限                                                │
│ ● フルアクセス                                      │
│ ○ 選択した権限のみ…                                 │
│     ☐ 読取  ☐ 書込  ☐ 管理者                      │
│                                                     │
│ チームアクセス                                      │
│ ● アクセス権を持つすべてのチーム                    │
│ ○ 選択したチームのみ…                               │
│                                                     │
│ [キャンセル] [作成]                                 │
└─────────────────────────────────────────────────────┘

権限はキーが何ができるかを制御します。フルアクセスはすべてのスコープを付与します。または個別スコープ（読取、書込、管理者）を選択できます。External APIは現在読み取り専用なので、分析用には読取キーで十分です。
チームアクセスはキーがアクセスできるワークスペースを制御します。アクセス権を持つすべてのチームのままにするか、特定のチームに制限してください。

ステップ3：キーを保存

重要： 完全なキーは1回だけ表示されます。ダイアログを閉じる前にコピーしてください。

┌─────────────────────────────────────────────────────┐
│ 新しいAPIキー                                       │
│ ─────────────────────────────────────────────────── │
│                                                     │
│ このAPIキーは今後表示されません。                   │
│ 今すぐコピーしてください。                          │
│                                                     │
│ zv_abc123xyz789...                                 │
│                                                     │
│ [コピー]                                            │
│                                                     │
└─────────────────────────────────────────────────────┘

キーの形式

すべてのAPIキーは単一の形式を使用します：

プレフィックス：zv_
キーはセキュリティのためSHA-256ハッシュとして保存されます
完全なキーは作成時に1回だけ表示されます

個別のテスト/サンドボックスキータイプはありません。開発と本番環境を分離するには、わかりやすい名前で複数のキーを作成してください。

キーの権限

キーを作成するときは、権限（スコープ）とチームアクセスを選択します。

スコープ	付与されるもの
フルアクセス	すべてのスコープ
読取	External APIへの読み取り専用アクセス
書込	書き込みエンドポイント（`POST`/`PATCH`/`DELETE`）
管理者	管理者専用エンドポイント（チームの所有者または管理者ロールが必要）

以下に記載されているExternal API表面は現在読み取り専用なので、分析用には読取キー（またはフルアクセス）で十分です。トラッキング取り込みはAPIキーを使用せず、トラッキングスクリプトを使用します。

APIキーがアクセスできるもの

エンドポイントカテゴリ	エンドポイント
分析	GET /analytics/:websiteId（概要、訪問者、ページ、国、テクノロジー）
ウェブサイト	GET /websites、GET /websites/:websiteId
ヒートマップ	GET /heatmaps/:websiteId/pages
セッションリプレイ	GET /replays/:websiteId/sessions
エラーグループ	GET /errors/:websiteId/groups
使用状況	GET /usage

チームアクセス制限

すべてのチーム

デフォルトでは、キーはアカウントが属するすべてのチーム（ワークスペース）と、それらの中のすべてのウェブサイトにアクセスできます：

最もシンプルな設定
ワークスペース全体を読み取る内部ツール向け

選択したチーム

キーを制限するには、**選択したチームのみ…**を選択し、アクセスを許可するチームを選択します。その後、キーはそれらのチームに属するウェブサイトにのみ機能します。

制限のユースケース

シナリオ	設定
1つのワークスペースのみのキー	選択したチーム（そのチームを選択）
すべてのワークスペース横断の内部ダッシュボード	アクセス権を持つすべてのチーム

キーの管理

すべてのキーを表示

個人用APIキーカードは、スコープ、マスクされたプレフィックス、最後の使用時刻を含む各キーをリストアップします：

┌─────────────────────────────────────────────────────┐
│ 個人用APIキー                    [+ 新しいキー]    │
│ ─────────────────────────────────────────────────── │
│                                                     │
│ Production    [フルアクセス]    zv_abc…             │
│ Dashboard     [読取]            zv_def…             │
│ Client A      [読取]            zv_ghi…             │
│                                                     │
└─────────────────────────────────────────────────────┘

キーの詳細

キーをクリックして詳細ビューを開きます：

名前、スコープ、チームアクセス
作成日時と最後に使用した日時
サーバー側アクティビティ（受け入れたイベント数とこのキーの最近のイベント）

キーを編集

詳細ビューで、メニュー（…ボタン）から編集を選択して、キー名を変更したり、スコープとチームアクセスを変更したりして、保存します。

キーを取り消す

キーが侵害または未使用の場合：

キーの詳細ビューを開きます
…メニューから取り消すをクリックします
確認します

キーは直ちに無効になります。キーを置き換えるには、古いキーを取り消して新しいキーを作成します。

キーのセキュリティ

ベストプラクティス

実践	理由
環境変数を使用する	ハードコードしない
最小限のスコープとチームアクセスを付与	影響範囲を制限
統合ごとに別々のキー	開発/本番とクライアントを分離
未使用のキーを取り消す	露出を減らす
アクティビティビューを監視	異常を検出

環境変数

キーを安全に保存：

# .envファイル（絶対にコミットしないこと！）
ZENOVAY_API_KEY=zv_abc123...

// コードでの使用
const apiKey = process.env.ZENOVAY_API_KEY;

キーのローテーション

Zenovayはキーをその場で再生成しません。ローテーションするには：

新しいキーを作成します
アプリケーションを更新します
すべてが機能することを確認します
古いキーを取り消します

APIキーの使用

cURL

curl https://api.zenovay.com/api/external/v1/websites \
  -H "X-API-Key: zv_YOUR_API_KEY"

JavaScript

const response = await fetch('https://api.zenovay.com/api/external/v1/websites', {
  headers: {
    'X-API-Key': process.env.ZENOVAY_API_KEY,
  }
});

Python

import requests

response = requests.get(
    'https://api.zenovay.com/api/external/v1/websites',
    headers={'X-API-Key': api_key}
)

トラブルシューティング

APIは{ "error": { "message": "...", "code": "..." } }の形式でエラーを返します。

APIキーが見つからないまたは無効

{
  "error": {
    "message": "Invalid API key",
    "code": "UNAUTHORIZED"
  }
}

401を返します。確認：

キーがzv_プレフィックス付きで正しくコピーされている
余分なスペースまたは改行がない
キーが削除されていない
X-API-KeyまたはAuthorization: Bearerとして送信している

プランにAPIアクセスが含まれていない

{
  "error": {
    "message": "The Zenovay API requires a paid plan. Upgrade to Pro or higher to use API keys.",
    "code": "API_PAID_PLAN_REQUIRED"
  }
}

403を返します。External APIはProプラン以上が必要です。ワークスペースをアップグレードしてからキーを作成してください。

このウェブサイトは禁止

{
  "error": {
    "message": "Forbidden",
    "code": "FORBIDDEN"
  }
}

403を返します。キーはリクエストされたウェブサイトにアクセスできません。ウェブサイトはキーのチームアクセス範囲外のチームに属しているためです。そのウェブサイトをカバーするチームアクセスを持つキーを使用するか、キーのチームアクセスを広げてください。

アクティビティと使用状況

キーの詳細ビューを開いて、サーバー側アクティビティを確認します：受け入れたイベント数（過去24時間、過去7日間、全期間）と、そのキーに帰属する最近のイベント。これはキーが稼働中であることを確認し、予期しない使用を検出するのに役立ちます。