Retell AI セキュリティ基礎

概要

Retell AI APIキー、トークン、アクセス制御のセキュリティベストプラクティスです。

前提条件

• Retell AI SDKがインストールされていること
• 環境変数の理解
• Retell AIダッシュボードへのアクセス

手順

ステップ 1: 環境変数の構成

# .env (絶対にgitにコミットしないこと)
RETELLAI_API_KEY=sk_live_***
RETELLAI_SECRET=***

# .gitignore
.env
.env.local
.env.*.local

ステップ 2: シークロット・ローテーション の実装

# 1. Retell AIダッシュボードで新しいキーを生成する
# 2. 環境変数を更新する
export RETELLAI_API_KEY="new_key_here"

# 3. 新しいキーが機能することを確認する
curl -H "Authorization: Bearer ${RETELLAI_API_KEY}" \
  https://api.retellai.com/health

# 4. ダッシュボードで古いキーを無効化する

ステップ 3: 最小権限の原則を適用

環境	推奨スコープ
開発	read:*
ステージング	read:*, write:limited
本番	必要なスコープのみ

出力

• セキュアなAPIキーの保存
• 環境別のアクセス制御
• 監査ログの有効化

エラーハンドリング

セキュリティの問題	検出方法	対策
APIキーの漏洩	Git スキャニング	直ちにローテーション
過度なスコープ	監査ログ	アクセス権限の削減
ローテーションの未実施	キー経過日数チェック	ローテーションをスケジュール

例

サービスアカウント パターン

const clients = {
  reader: new RetellAIClient({
    apiKey: process.env.RETELLAI_READ_KEY,
  }),
  writer: new RetellAIClient({
    apiKey: process.env.RETELLAI_WRITE_KEY,
  }),
};

Webhook シグネチャ検証

import crypto from 'crypto';

function verifyWebhookSignature(
  payload: string, signature: string, secret: string
): boolean {
  const expected = crypto.createHmac('sha256', secret).update(payload).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

セキュリティ チェックリスト

• APIキーを環境変数に設定
• .env ファイルを .gitignore に追加
• 開発/ステージング/本番で異なるキーを使用
• 環境ごとに最小限のスコープを設定
• Webhook シグネチャを検証
• 監査ログを有効化

監査ログ

interface AuditEntry {
  timestamp: Date;
  action: string;
  userId: string;
  resource: string;
  result: 'success' | 'failure';
  metadata?: Record<string, any>;
}

async function auditLog(entry: Omit<AuditEntry, 'timestamp'>): Promise<void> {
  const log: AuditEntry = { ...entry, timestamp: new Date() };

  // Retell AI アナリティクスにログを送信
  await retellaiClient.track('audit', log);

  // コンプライアンス対応のためローカルにも記録
  console.log('[AUDIT]', JSON.stringify(log));
}

// 使用例
await auditLog({
  action: 'retellai.api.call',
  userId: currentUser.id,
  resource: '/v1/resource',
  result: 'success',
});

リソース

• Retell AI セキュリティガイド
• Retell AI APIスコープ

次のステップ

本番環境へのデプロイメントについては、retellai-prod-checklist を参照してください。