> ## Documentation Index
> Fetch the complete documentation index at: https://intervyo.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 認証

> x-api-key ヘッダーを使用して intervyo.ai REST API へのリクエストを認証する方法。

すべての API リクエストは、`x-api-key` ヘッダーで送信されるワークスペース単位の **APIキー** によって認証されます。キーはチームダッシュボードで作成され、`iv_live_` というプレフィックスが付きます。

## APIキーを取得する

<Steps>
  <Step title="開発者設定を開く">
    サインインし、ワークスペース内で **Settings → Developer → API keys** を開きます。
  </Step>

  <Step title="API Keys を開く">
    チームダッシュボードで **Developer → API Keys** に移動します。
  </Step>

  <Step title="キーを作成する">
    **New API key** をクリックします。監査ログを読み取れるようにするため、そのキーを使用する連携先に合わせた名前（例: `ats-sync-prod`、`embed-widget-staging`）を付けます。
  </Step>

  <Step title="キーを作成する">
    **New API key** をクリックします。監査ログを読みやすく保つため、そのキーを使用する連携先に合わせた名前（例: `ats-sync-prod`、`embed-widget-staging`）を付けます。
  </Step>

  <Step title="必要最小限のスコープを選ぶ">
    スコープは加算式です。キーには必要な範囲だけを与えてください。セッションを作成するだけのキーに、参加者への読み取りアクセスは不要です。

    | スコープ                 | 許可される操作                        |
    | -------------------- | ------------------------------ |
    | `sessions:read`      | セッション、スコアカード、トランスクリプト、録画の読み取り。 |
    | `sessions:write`     | セッションの作成 + キャンセル。              |
    | `participants:read`  | 参加者と履歴書データの読み取り。               |
    | `participants:write` | 参加者の作成 + 更新。                   |
    | `templates:read`     | 評価テンプレート + ステージの読み取り。          |
    | `webhooks:write`     | Webhook エンドポイントの管理。            |
  </Step>

  <Step title="必要最小限のスコープを選ぶ">
    スコープは加算式です。キーには必要な範囲だけを付与してください。

    | スコープ                                     | 付与される権限                      |
    | ---------------------------------------- | ---------------------------- |
    | `candidates.read` / `.write` / `.delete` | 参加者の読み取り / 作成・更新 / 削除        |
    | `interviews.read` / `.write`             | セッションとエージェントプロファイルの読み取り / 作成 |
    | `evaluation_templates.read` / `.write`   | 評価テンプレートの読み取り / 管理           |
    | `evaluation_stages.read` / `.write`      | ステージの読み取り / 管理               |
    | `programs.read` / `.write`               | プログラムと登録の読み取り / 管理           |
  </Step>

  <Step title="シークレットをコピーする">
    キー全体は **一度だけ** 表示されます。すぐにシークレットマネージャーへコピーしてください。後でローテーションすることはできますが、平文を復元することはできません。
  </Step>

  <Step title="シークレットをコピーする">
    キー全体（`iv_live_…`）は **一度だけ** 表示されます。すぐにシークレットマネージャーへコピーしてください。後でローテーションすることはできますが、平文を復元することはできません。
  </Step>
</Steps>

## リクエストを認可する

`x-api-key` ヘッダーでキーを送信します。

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://www.intervyo.ai/api/v1/sessions" \
    -H "x-api-key: iv_live_your_key_here"
  ```

  ```ts TypeScript theme={null}
  await fetch("https://www.intervyo.ai/api/v1/sessions", {
    headers: { "x-api-key": process.env.INTERVYO_API_KEY! },
  });
  ```

  ```python Python theme={null}
  import os, requests

  requests.get(
      "https://www.intervyo.ai/api/v1/sessions",
      headers={"x-api-key": os.environ["INTERVYO_API_KEY"]},
  )
  ```
</CodeGroup>

<Warning>
  APIキーをブラウザ、モバイルバンドル、その他のクライアント側に **絶対に** 含めないでください。キーはそのスコープに対してワークスペース全体へのアクセスを許可します。API は自社のバックエンドから呼び出すか、短命の参加者トークンに引き換える [埋め込みウィジェット](/jp/guides/embed-widget) を使用してください。
</Warning>

## セッション（Cookie）認証

サインイン済みのダッシュボードセッションから行うリクエストは、キーの代わりに Cookie で認証できます。これらの呼び出しでは、API がワークスペースを解決できるよう、チームスラッグを `accountSlug` クエリパラメータとして渡してください。

```bash theme={null}
curl "https://www.intervyo.ai/api/v1/participants?accountSlug=<your-team-slug>"
```

ほとんどのサーバー間連携では、Cookie 認証ではなく APIキーを使用すべきです。

## キーをローテーションする

APIキーは自動的には失効しません。組織のシークレット管理スケジュール（90日が一般的）に従ってローテーションしてください。

<Steps>
  <Step title="置き換え用のキーを作成する">
    古いキーと並行して新しいキーを生成します。両方を同時に有効にできます。
  </Step>

  <Step title="置き換え用のキーを作成する">
    古いキーと並行して新しいキーを生成します。両方を同時に有効にできます。
  </Step>

  <Step title="新しいキーをデプロイする">
    シークレットマネージャー経由で新しい値を展開します。稼働中のすべてのサービスがそれを取得します。
  </Step>

  <Step title="新しいキーをデプロイする">
    シークレットマネージャー経由で新しい値を展開し、すべてのサービスがそれを取得するようにします。
  </Step>

  <Step title="古いキーを失効させる">
    トラフィックが移行したことを確認したら（古いキーの監査ログが静かになります）、そのキーを失効させます。失効は即座に反映されます。失効したキーを使用した処理中のリクエストは `401` を返します。
  </Step>

  <Step title="古いキーを失効させる">
    トラフィックが移行したら（古いキーの監査ログが静かになります）、そのキーを失効させます。失効は即座に反映されます。失効したキーを使用した処理中のリクエストは `401` を返します。
  </Step>
</Steps>

## レート制限

制限はプランに応じて変動します。すべてのレスポンスにはレート制限ヘッダーが含まれます。

```http theme={null}
X-RateLimit-Limit:      120
X-RateLimit-Remaining:  118
X-RateLimit-Reset:      1735689600
```

`429 Too Many Requests` には `Retry-After` ヘッダー（秒単位）が含まれます。バックオフして再試行するか、処理をバッチ化してリクエスト頻度を下げてください。

## 認証エラー

<ResponseField name="401 Unauthorized">
  APIキーが欠落、不正な形式、または失効しています。`x-api-key` ヘッダーを確認し、**Developer → API Keys** でキーを検証してください。
</ResponseField>

<ResponseField name="402 Payment Required">
  ワークスペースに有効な有料プランがない（またはクレジットを使い切っている）状態です。候補者向けの応募フローはトライアル中も引き続き機能しますが、プログラムによるセッション作成には有料プランが必要です。
</ResponseField>

<ResponseField name="403 Forbidden">
  キー自体は有効ですが、このエンドポイントが必要とするスコープがありません。不足しているスコープを追加するか、別のキーを使用してください。
</ResponseField>

<Note>
  OAuth、SSO スコープ付きトークン、またはサービスアカウントが必要ですか？ [hi@intervyo.ai](mailto:hi@intervyo.ai) までお問い合わせください。
</Note>