認証ガイド

Bright Data の全プロダクトは、用途に応じて API Access（Bearer トークン） と Native Access（プロキシ認証） の 2 系統で認証します。どちらを使っても課金レートは同じで、選択はユースケースに応じて行います。

一次情報: Authentication | Bright Data Docs

認証方式の全体像

• 両方式とも同一レートで課金されます。料金は利用プロダクトのプランに依存します。
• 組織によっては 両方併用（API は SERP/Unlocker、Native は既存ブラウザ）も一般的な選択です。

API Access（Bearer トークン）

Bright Data API（Unlocker / SERP / Browser / Crawl / Scrapers / Discover / Deep Lookup / MCP など）に最も広く使える方式です。JSON レスポンスを素直に扱えるため、ETL やアプリケーションに直結しやすいのが特徴です。

最小リクエスト

curl -X POST https://api.brightdata.com/request \
  -H "Authorization: Bearer $BRIGHTDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "zone": "web_unlocker1",
    "url": "https://example.com",
    "format": "raw"
  }'

• $BRIGHTDATA_API_KEY は .env など環境変数で保管し、ソースコードに直書きしないこと。
• zone は Native Access の PROXY_NAME と同じ値を指定します。API 側でも Native 側でも同じゾーンを指す設計になっています。

API キーの発行と運用

• アカウント作成時にデフォルト API キーが 1 本発行されます。追加キーは Account settings から作成します。
• API キーは生成直後に一度だけ平文表示されます。安全な場所に保管してください（シークレットマネージャ推奨）。
• Refresh を実行すると新キーが生成され、旧キーは即時無効化されます。段階的な入れ替えはできないため、切替直前に発行するか、複数キーを用意して順次切替します。
• API キー作成は管理者アカウントのみ可能です。

権限モデル（PermissionLevel）

最小権限の原則に従い、用途別にキーを分けて発行します。

• ADMIN 権限キーは作成後に平文で再表示できません。パスワード同等の機密として扱います。
• 実運用ジョブ（ETL、バッチ、Lambda など）には USER または OPS を割り当て、ADMIN は人間の操作のみに限定します。

有効期限とローテーション

• API キーには有効期限を設定できます。期限超過のキーはリクエストが拒否されます。
• Unlimited（無期限）も選択できますが、明示的な期限設定が推奨です。
• 推奨ローテーション: 90 日。失効時は Refresh で即時切替、もしくは新規キー発行 → 旧キー削除。

Native Access（プロキシ認証）

既存のクローラ、ブラウザ、スクリプトが host:port + username:password のプロキシ設定を前提にしている場合は、Native Access が最短です。実装変更を最小限に抑えられます。

対応プロダクト

• Datacenter / ISP / Residential / Mobile Proxy（全プロキシネットワーク）
• Web Unlocker
• Scraping Browser

接続文字列の仕様

Host:     brd.superproxy.io
Port:     33335
Username: brd-customer-<ACCOUNT_ID>-zone-<PRODUCT_NAME>
Password: <PROXY_PASSWORD>

• 大文字小文字を区別します（case sensitive）。
• スペースを含めない 1 つの連続文字列です。
• - がサブ要素の区切り、: が username と password の区切りです。

curl での最小確認

curl --proxy brd.superproxy.io:33335 \
  --proxy-user "brd-customer-$ACCOUNT_ID-zone-$PRODUCT_NAME:$PROXY_PASSWORD" \
  -k https://geo.brdtest.com/welcome.txt

SSL 証明書の注意

• API Access: 原則不要です。
• Native Access: Residential network と Web Unlocker を KYC なしで利用する場合、Bright Data の CA 証明書を信頼する必要があります（curl -k や証明書インストールで対応）。

どちらを使うかの判断フロー

以下のいずれかに該当するなら API Access を優先:

• バッチ処理 / API 統合 / CI ジョブ / データパイプラインが主目的
• レスポンスを JSON で扱いたい
• Unlocker API / SERP / Browser / Crawl / Scrapers / Functions / Marketplace を中心に使う

以下のいずれかに該当するなら Native Access を優先:

• 既存ツールが --proxy / --proxy-user 前提のプロキシ設定を持つ
• ブラウザ（Playwright / Selenium / Puppeteer）やクローラを直接プロキシ経由で動かす
• 出力が HTML 中心で、後段で独自パーサにかける

大規模運用では API と Native を併用し、ワークロードごとに最適な方式を使い分けるパターンが一般的です。

セキュリティ運用の 5 原則

1. 最小権限: 日常の API 呼び出しには USER / OPS を使い、ADMIN は金庫管理。
2. 期限必須: すべてのキーに明示的な有効期限を設定し、90 日程度でローテーション。
3. 職務分離: 経理は FINANCE、運用は OPS、開発者は USER。1 本のキーを共有しない。
4. シークレット管理: ソース直書き禁止。環境変数 / シークレットマネージャ（Vault, AWS Secrets Manager, GCP Secret Manager 等）に保管。
5. Native 管理: ACCOUNT_ID / PRODUCT_NAME / PROXY_PASSWORD の命名・保管・再生成手順を Runbook 化。

ユースケース別の推奨構成

社内データ収集 API 基盤

• 認証: API Access
• 理由: Bearer 認証で統一、JSON を ETL に直結できる
• 運用: ジョブには USER / OPS キー、90 日ローテ、失効時は Refresh で即時切替

既存クローラの最短リフト

• 認証: Native Access
• 理由: --proxy / --proxy-user 設定をそのまま流用でき、実装変更コスト最小
• 運用: プロダクト単位で PRODUCT_NAME を分離、パスワード定期更新

厳格な権限分離を伴う大規模運用

• 認証: API Access + Native 併用
• 理由: 職務・接続形態の双方で分離設計が可能
• 運用: ADMIN は金庫、FINANCE / OPS / USER を職務分離で発行、全キーに期限設定

セルフチェックリスト

• どの認証方式を採用するか決めたか（API / Native / 併用）
• 権限レベルが最小権限になっているか
• 有効期限とローテーション方針が定義されているか
• ADMIN キーの保管方法が決まっているか
• Native 利用時、ACCOUNT_ID / PRODUCT_NAME / PROXY_PASSWORD の管理手順があるか
• （該当時）SSL 証明書要件を確認したか

次に読む

• ハンズオン Step 1: 認証と最初の API 呼び出し
• ロードマップ Lv1: 入門
• 基礎: 認証方式の詳細
• 用語集