🌐

【2026最新版】Box API × Python 導入完全手順｜JWT認証・管理者設定・地雷回避の決定版

に公開
Python
API
JWT
Box
DX
tech

0. はじめに：なぜ今、この手順書が必要なのか

「Box APIの解説記事、どれも画面が古くて参考にならない……」
「ドキュメント通りに進めたのに、謎の404エラーで詰んだ……」

2026年現在、Boxの管理画面（UI）やセキュリティ仕様は劇的に変化しています。数年前の「古い正解」をなぞっても、今のBoxでは動かないどころか、気づけば有料プランへ誘導されていることすらあります。

本記事は、現役のDX担当である私が、「改めてゼロから」構築をやり直し、すべての地雷を踏み抜いた末に完成させた「動く手順書」です。

忙しいあなたが、環境構築ごときに貴重な時間を溶かす必要はありません。この記事を読みながら、最短ルートで「自分専用の自動化環境」を手に入れてください。

https://zenn.dev/kmg/books/9eebd2060b6b81

本記事は、0からPythonでBox API環境を構築する「実践編」です。最短ルートで「動くもの」を作りたい方向けに執筆しています。

「まだ構築はしないが、Box API特有の仕様や、あらかじめ知っておくべき地雷（概念）だけ把握しておきたい」という方は、先にこちらの記事をチェックしてください。

https://zenn.dev/kmg/articles/f5ee3196640671

1. このガイド全体の流れ

迷子にならないよう、ゴールまでの地図を先に提示します。

  1. フェーズ1：開発者サンドボックスの作成
    • 有料プランへの「拉致」を回避し、0円で全権限を持つ環境を作ります。
  2. フェーズ2：アプリ作成と「黄金の3箇条」設定
    • 24時間無人稼働（JWT）を実現するための「正しい設定」を断言します。
  3. フェーズ3：合鍵「config.json」の発行と「承認の儀式」
    • 二段階認証と管理者承認を突破し、APIを有効化します。
  4. フェーズ4：Python接続テスト
    • 2026年版の最新ライブラリ構成で「Hello Box!」を確認します

2. フェーズ1：開発者サンドボックスの作成

Step 1. 「シークレットウィンドウ」で専用口から入る

Box API、特に「無人稼働」ができるJWT認証を利用する場合、個人用アカウントでは「管理画面」が出現せず、設定が詰んでしまいます。

「個人アカウントでとりあえず試そう」は最大の地雷です。
必ず以下のシークレットモード（Ctrl+Shift+N)を開いて下記のURLを張り付けて、無料のサンドボックス環境を作成してください。
(https://account.box.com/signup/n/developer)

この画面になっていたらOKです

Step 2. 登録フォーム入力（Gmailエイリアスの裏技）

フォームが表示されたら入力します。ここで**「検証用アカウント量産の裏技」**を使います。

Boxのために新しいGoogleアカウントを作る必要はありません。既存のGmailアドレスの @ の前に +好きな文字 を足すだけで、Boxは「新規ユーザー」として認識し、メールは元の受信トレイに届きます。

  • 入力例: yourname+box2026@gmail.com
  • 必須チェック: 「サービス利用規約」のみチェックすればOKです。私は人間ですにもチェック

Step 3. メール認証

登録ボタンを押すと「We've Sent You a Confirmation Email」と表示されます。
元のメールアドレスの受信トレイを確認し、届いたメール内の [Verify Email] ボタンをクリックしてください。

Step 4. 「約束の地」へ到達

ログイン後、画面左が黒いサイドバーになり、**「My Platform Apps」**という画面（または開発者コンソール）が表示されれば成功です。
これが、個人用アカウントとは違う、あなただけの「検証用企業環境」です。

3. フェーズ2：アプリ作成と「黄金の3箇条」設定

管理者権限のある環境に入れたら、自動化の「心臓部」を作ります。
ここは適当に選ぶと「後で動かない」原因になるため、**「なぜそれを選ぶのか」**という理由を含めて解説します。

Step 0. 日本語化する

その後の説明のしやすさを重視して日本語化します。
必須ではありませんので、必要ない方はstep1へスキップください。

１．画面右上の 人型アイコン をクリック。

２．[Account Settings]（アカウント設定）をクリック。

３．以下の画面が出た場合、必ず指示に従ってクリックしてください。

訳：あなたは開発者なので、画面がごちゃごちゃしないように、開発に関係ない設定（言語や通知など）は隠しておきましたよ。全部見たければここをクリックして

４．[General] タブの下の方にある 「Language」 を 「日本語」 に変更。
５．[Time Zone] もついでに 「(GMT+09:00) Tokyo」 にしておくとログが見やすくなります。
６．右上の [Save Changes] をクリック。

７．開発者コンソールのタブに戻る。

Step 1. 「カスタムアプリ」と「JWT」を選択する

１. [アプリの新規作成] をクリック

２. アプリ名（例: Box_Auto_Bot）を入力し、認証方法：[サーバー認証（JWT使用）] を選択。

  • 理由（超重要）:
    • ユーザー認証 (OAuth 2.0): ブラウザで人間がログインする必要があります。トークンがすぐ切れるため、夜間の無人実行には向きません。
    • サーバー認証 (JWT): 「電子署名付きの鍵ファイル」を使って認証します。人間が寝ていても、プログラムが勝手にログインして動き続けられます。 自動化する場合はこれが正解です。
    • クライアント資格情報許可 (CCG): Boxが推奨する新しい認証方式ですが、Python SDKでの導入実績や情報がまだ少なく、JWTの方が安定しています。 今回は「確実に動く」ことを最優先するため、JWTを選びます。

４. 作成ボタンを押す。

Step 2. 「構成」タブで3つの権限を付与する

アプリが作成されたら、[構成 (Configuration)] タブを開きます。
ここはデフォルト設定のままでは「権限不足」でエラーになります。以下の3箇所を変更してください。

① アプリアクセスレベル

設定: アプリ + Enterpriseアクセス を選択 *社内規定でアプリアクセスのみに設定されている場合はそちらをお選びください。

  • 理由:
    • アプリアクセスのみ: ボットは招待された場所しか触れません。会社のフォルダは見えません。
    • アプリ + Enterprise: ボットが**「システム管理者」と同等の視界**を持ち、社内の全フォルダにアクセス可能になります。監査や一括処理には必須です。

＊【重要】セキュリティポリシー上の注意点
企業によっては、セキュリティ上の規定により アプリ + Enterpriseアクセス が規制されている場合があります。
その場合、アプリでのアクセスのみ を選び、後で**「ボットが触るフォルダだけ」**を個別に招待（コラボレーション）することで対処可能です。
しかし、その場合ボットは全社の監査ログが見えなくなります。監査や大規模運用をしたい場合は、必ずこの設定（Enterpriseアクセス）で申請してください。

② アプリケーションスコープ

設定: Boxに格納されているすべてのファイルとフォルダの読み取り/書き込み にチェック

  • 理由:
    • デフォルトでは「読み取り」しか許可されていません。これだと、Pythonで作ったCSVやExcelをBoxに**「保存（アップロード）」**できません。必ず「書き込み」も許可してください。

③ 高度な機能 (Advanced Features)

設定: ユーザーとして操作を実行 (Make API calls using the as-user header) にチェック

  • 理由:
    • ここがプロのこだわりポイントです。
    • 通常、ボットは「ボット自身」として操作しますが、この権限があると**「退職したAさんになりすまして、Aさんのゴミ箱からファイルを救出する」**といった神業が可能になります。将来のトラブル対応のために、必ずチェックを入れてください。

すべてのチェックを入れたら、画面右上の [変更を保存] を必ず押してください。

4. フェーズ3：合鍵「config.json」の発行と「承認の儀式」

https://zenn.dev/kmg/books/9eebd2060b6b81

それでは、ラストスパートの合鍵「config.json」の発行と「承認の儀式」やっていきましょう

Step 1. 二段階認証の設定（鍵の発行準備）

Step 1.
Boxはセキュリティが厳重なため、プログラム用の鍵（秘密鍵）を発行するには、あなた自身のアカウントの二段階認証設定が必須となります。
１．公開キー/秘密キーペアの生成をクリックしたら、画面上部に「この操作を実行するには、2要素認証を有効にする必要があります。」が表示されるので「settings」をクリック。

２．アカウントタブの2段階認証の設定をクリック

3．任意の方法で認証を実施。認証アプリを推奨します。今回は認証アプリで進めます。
認証アプリ（推奨）:
理由: JWT認証で鍵を発行する際に、最もセキュリティレベルが高く、Box側が推奨しているのがこの方式だからです。SMSやメール認証よりも信頼性が高いため、一度設定すると後々セキュリティチェックで引っかかりにくいです。
SMSテキストメッセージ:
理由: 最も手軽ですが、セキュリティレベルが低いため、Boxの仕様変更で将来的にこの認証が認められなくなるリスクがあります。
メール:
理由: 認証アプリやSMSが使えない場合の最終手段です。メールサーバーにトラブルがあった場合使えなくなります。

二段階認証アプリ（Google Authenticator等）でQRコードで読み込み、表示されているコードを入力。

2段階認証が有効になっていることを確認し、開発者コンソールに戻る

合鍵のダウンロード

１．[構成] タブの中ほどにある [公開キー/秘密キーペアの生成] をクリック。
config.json がダウンロードされます。これがボットの「命」です。

管理者によるアプリの承認

合鍵（json）を持っていても、家主（管理者）が「入ってよし！」と許可しない限り、ボットは動きません。

  1. [承認] タブで [承認用に送信] をクリック。

  2. メールが届き、Platformアプリの詳細を確認をクリック

  3. 作成したアプリの右側にある ... から [アプリを承認] を実行。

4. フェーズ4：Python接続テスト

Step 1. 作業環境の準備（フォルダとファイル）

まず、すべてのファイルを一箇所に集めます。
デスクトップなどに新しい作業用フォルダを作成します。（例: Box_API_Project）
ダウンロードした config.json を、このフォルダの中に移動させます。

Step 2. コマンドプロンプトの起動と仮想環境の作成

プロジェクト専用のクリーンな環境を作るため、仮想環境（venv）を利用します。
作成したフォルダ（Box_API_Project）を開き、アドレスバーに cmd と入力して Enterキーを押します。
以下のコマンドを1行ずつコピーして実行してください。

# 1. フォルダに移動する。Box_API_Project の部分は、実際にファイルを入れたフォルダ名に合わせてください
cd C:\Box_API_Project

# 1. プロジェクト専用の部屋（仮想環境）を作る
python -m venv venv

# 2. その部屋に入る（環境の有効化）
venv\Scripts\activate
# ※成功すると、行の先頭に (venv) と表示されます

Step 3. Box操作に必要なライブラリのインストール

PythonがBoxと通信するために必要な「通訳ソフト（ライブラリ）」をインストールします。

# 安定稼働を重視し、安定版のBox SDKとデータ処理用のPandasをインストール
pip install "boxsdk[jwt]<10.0.0" pandas

Step 4. 接続テストコードの作成

以下のコードをコピーし、メモ帳などに貼り付けて connect_test.py という名前で保存してください。（保存先は config.json と同じフォルダ）

import os
from boxsdk import JWTAuth, Client

# ダウンロードしたJSONファイル名を正確に合わせてください
CONFIG_FILE = 'config.json'

def main():
    # 1. 認証（合鍵を使ってドアを開ける）
    base_dir = os.path.dirname(os.path.abspath(__file__))
    config_path = os.path.join(base_dir, CONFIG_FILE)

    if not os.path.exists(config_path):
        print("エラー: config.jsonが見つかりません。")
        return

    try:
        auth = JWTAuth.from_settings_file(config_path)
        client = Client(auth)
        
        # 2. 自分の名前を聞く（これができれば成功！）
        me = client.user().get()
        print(f"🎉 接続成功！ ボット名: {me.name} (ID: {me.id})")
        
        # 3. 次のステップへの重要事項
        # ※ファイル一覧を取得したり操作したりしたいフォルダへ招待が必要です
        print(f"📩 このメアドを操作したいフォルダに招待してください: {me.login}")
        
    except Exception as e:
        print(f"❌ 接続失敗: {e}")
        # 認証エラーの具体的なヒントは「よくあるエラー」を参照
        
if __name__ == "__main__":
    main()

Step 5. 接続テストコードの作成

コマンドプロンプトでいかを実行。

python connect_test.py

接続成功！ と表示されれば、あなたの環境構築は完全勝利です。お疲れ様でした！

５. 「動けばいい」のその先へ：実務レベルの自動化とは

お疲れ様でした！これであなたは、Boxの情報を自由自在に操る「武器（API）」を手にしました。
環境構築という高い壁を突破しても、実務で運用するには「次の壁」が待っています。

  • APIの回数制限（リミット）をどう管理し、回避するか？
  • 調査結果を、そのまま会議資料にできる「色付きの綺麗なExcel」にどう変換するか？

ただ「コンソールに文字が出た」と喜ぶレベルから、**「現場で使えるガバナンスツール」**に昇華させるには、さらに高度なロジックが必要です。

※「リンク切れは赤、名称変更はオレンジ、正常なら緑」
この判別をPythonで自動で行い、Excelに美しく出力する。これこそが、現場が求めている「自動化」の形です。

６. 結び：あなたの「数日間」を3,000円でショートカットしませんか？

私がこれらすべての地雷を実体験で踏み抜き、AIとの壁打ちを繰り返して完成させた「答え」を、Zennの本（Book）としてパッケージ化しました。

  • 第3章：そのままコピペで動く、色付きExcel出力・通知機能対応の「全ソースコード」

正直に言います。

独学でエラーログをググり、不親切な英語のドキュメントを読み漁る時間を過ごすなら、この本を買って**「30分で構築を終わらせ、本来やらなければいけない実務時間にあてる」**方が、時間を圧倒的に有効活用できます。

🚀 リリース記念：期間限定価格

現在、リリース記念として、通常価格より抑えた3,000円で公開しています。
（※一定部数を超えた段階で、適正価格である5,000円へ値上げ予定です）

あなたの貴重な時間を、地雷除去に使うのはもうやめにしませんか？
「解決済みの正解」を手に入れて、明日から運用を始めましょう。

私が公開している本「Box Link Patrol Pro」 Boxを監視し続ける「完全自動パトロールシステム」の構築ガイドと全コードを公開しています。

https://zenn.dev/kmg/books/9eebd2060b6b81

Discussion