2026.11.02 業務システム

Box APIとは：認証4方式の選び方とファイル操作・メタデータ・権限付与の実装手順

Q: レート制限に引っかかったときはどう処理すればよいですか？

429が返ったら、 retry-after ヘッダーの秒数だけ待って再試行します。公式SDKでは、この再試行は自動です。それでも頻発するなら、処理を用途別のアプリ（それぞれのサービスアカウント）や利用者に分ける、検索を毎秒6回以内に抑える、夜間の大量処理を日中の連携と時間帯で分ける、の順に見直します。制限は利用者ごとに数えられるため、1つのアカウントに全処理を集めない設計が効きます。

Box APIとは：認証4方式の選び方とファイル操作・メタデータ・権限付与の実装手順

Box APIは、クラウドストレージBoxのファイル・フォルダ・メタデータ・共有権限を、自社システムからHTTPで操作するためのREST APIです。この記事では、Box APIとは何かを押さえたうえで、OAuth 2.0・CCG・JWT・App Tokenの4つの認証方式の選び方、curlとPython SDK v10でのトークン取得、ファイルのアップロード、メタデータの付与と検索、コラボレーションによる権限付与までを、コード例付きで順に説明します。数値と仕様は2026年11月時点のBox公式ドキュメントに基づきます。

まとめ：Box APIで連携を作る前に決める認証・上限・権限の結論

社内システムからBoxを操作する連携なら、認証はClient Credentials Grant（CCG）を選び、サービスアカウントとして動かすのが基本形です。利用者本人の画面からBoxを開かせるアプリだけがOAuth 2.0の対象になります。CCGとJWTはどちらも管理者の承認が済むまでAPIを呼べないので、Box管理者との調整を開発の最初に置いてください。

実装上の境界は数字で覚えておくと設計が速くなります。直接アップロードは50MBまで、分割アップロードは20MB以上、一般のAPI呼び出しは利用者ごとに毎分1000件です。権限は上位フォルダから下位へ流れ、下位で絞れません。権限設計を誤ると後から直せないため、フォルダ構成は連携の実装より先に固めます。

書類の分類や検索が要件に入るなら、メタデータのテンプレートを使う連携に価値があります。ファイルの置き場を変えるだけの要件なら、iPaaSなどの既製の連携で済ませ、APIを使う開発は見送る判断も成り立ちます。

Box APIでできることとエンドポイント・SDK・バージョンの全体像

api.box.comとupload.box.comの2系統で動くBox APIの構成

Box APIの通常の呼び出しはhttps://api.box.com/2.0配下に送ります。ファイル本体の送信だけは別ドメインで、公式のアップロードガイドにあるとおり、送信先はupload.box.comです。ファイアウォールで外向き通信を許可制にしている企業では、2つのドメインを両方許可しないとアップロードだけが失敗します。

操作できる対象は、ファイルとフォルダの作成・移動・削除、版の管理、共有リンク、コラボレーション、メタデータ、Webhook、利用者とグループの管理などです。Boxの画面でできる操作の大半はAPIでも行えます。

Python・Java・Node・.NETとCLIの公式SDK、Pythonはv10系へ

公式のSDK一覧で提供中と示されているのは、Java、.NET、Python、Node、iOS、Box CLIです。Android SDKは2023年5月31日でサポートを終えており、代わりにJava SDKが案内されています。

Pythonはbox-python-sdkのv10系が現行で、初版は2025年9月17日です。インストールはpip install "boxsdk>=10"、importするパッケージ名はbox_sdk_genで、対応はPython 3.8以上です。v3系は2025年10月23日にサポート終了となりました。旧SDKのfrom boxsdk import Clientで書かれた解説記事のコードはそのまま動かないので、写経する前に版を確かめてください。

box-versionヘッダーでの版指定と省略時に2024.0になる挙動

Box APIは一部のエンドポイントに暦年ベースの版を付けています。APIバージョニングの方針によると、版はbox-versionヘッダーで指定し、省略すると初期版の2024.0として処理されます。安定版のサポート期間は最低12か月です。

省略時の挙動に頼ると、Box側で新しい版が既定になったときに挙動が変わる余地を残します。版付きのエンドポイントを使う連携では、ヘッダーを明示しておく書き方を勧めます。

認証方式をOAuth 2.0・CCG・JWT・App Tokenの4つから選ぶ手順

認証4方式の対象アプリと管理者承認の要否を用途別に比べる早見表

公式の認証ガイドの比較を、連携開発の判断に必要な列だけに絞ると次のとおりです。

方式	誰として動くか	管理者の承認	向いている用途
OAuth 2.0	ログインした利用者本人	未公開アプリを既定で無効にしている企業では必要	利用者が画面からBoxにつなぐWebアプリ
CCG	サービスアカウントか指定した利用者	必要	夜間バッチ、基幹システムからの自動連携
JWT	CCGと同じ	必要	秘密鍵を自社内に置きたいサーバー連携
App Token	アプリ自体	記載なし	Box Viewのプレビューなど限定的な用途

アクセストークンの有効期限は60分です。OAuth 2.0のリフレッシュトークンは60日有効で、使えるのは1回だけです。アプリの種類（利用者向けかサーバー向けか）は作成後に変えられないため、迷ったらCCGで作ってください。JWTとCCGは同じサービスアカウントを使えるので、鍵管理の方針が決まった後にJWTへ移る道も残ります。OAuth 2.0の認可フローそのものはOAuth 2.0の仕組みと認可フローの解説、JWTの署名の考え方はJWTの構造と署名検証の解説を参照してください。

サービスアカウントとして動かすCCGのトークン取得をcurlで試す

CCGのトークンはトークン発行エンドポイントにフォーム形式で送って取得します。CCGのガイドでは、box_subject_typeにenterpriseを指定するとサービスアカウント、userを指定するとその利用者として認証されると説明されています。

# Developer Console の Configuration タブで Client ID と Client Secret を確認しておく
curl -s -X POST "https://api.box.com/oauth2/token" \
  -H "content-type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=${BOX_CLIENT_ID}" \
  -d "client_secret=${BOX_CLIENT_SECRET}" \
  -d "box_subject_type=enterprise" \
  -d "box_subject_id=${BOX_ENTERPRISE_ID}"

# 返ってきた access_token でサービスアカウントのルート直下を一覧する
curl -s "https://api.box.com/2.0/folders/0/items?limit=100&usemarker=true" \
  -H "authorization: Bearer ${ACCESS_TOKEN}"

管理者の承認前に呼ぶとunauthorized_clientが返ります。CCGではリフレッシュトークンが発行されないため、60分ごとに同じリクエストでトークンを取り直します。サービスアカウントは新しい利用者として扱われるので、作成直後はどのフォルダにも招待されておらず、一覧が空でも異常ではありません。

Python SDK v10でCCG認証し利用者本人として呼び出す書き方

SDKを使うと、トークンの取得と期限切れ時の取り直しをSDK側が受け持ちます。次のコードはSDKの認証ドキュメントの書き方に沿ったものです。

# pip install "boxsdk>=10"
import os

from box_sdk_gen import BoxCCGAuth, BoxClient, CCGConfig

config = CCGConfig(
    client_id=os.environ["BOX_CLIENT_ID"],
    client_secret=os.environ["BOX_CLIENT_SECRET"],
    enterprise_id=os.environ["BOX_ENTERPRISE_ID"],
)
auth = BoxCCGAuth(config=config)
client = BoxClient(auth=auth)  # サービスアカウントとして動く

for item in client.folders.get_folder_items("0").entries:
    print(item.type, item.id, item.name)

# 特定の社員として操作する（Generate user access tokens の有効化と再承認が前提）
user_client = BoxClient(auth=auth.with_user_subject(user_id="12345678"))

利用者として動かす場合は、Developer ConsoleのAdvanced Featuresで「Generate user access tokens」を有効にし、アプリを承認し直す必要があります。誰の権限で操作したかが監査ログに残るので、利用者の書類を代理で動かす処理はwith_user_subjectで本人として実行する設計にしておくと、後の調査が楽になります。

ファイル操作の実装：一覧取得・50MBの壁・分割アップロード

ルートフォルダ0から辿る一覧取得とmarker方式のページング

フォルダ内アイテム一覧のリファレンスによると、ルートフォルダのIDは常に0で、1ページの上限は1000件です。ページングはoffset方式が既定ですが、大きなオフセットや件数の多いフォルダでは失敗しうると明記されています。数千件を超えるフォルダを全件たどる処理は、最初からusemarker=trueで書いてください。

fieldsを指定すると標準の項目が返らなくなる点にも注意が要ります。サイズと更新日時だけ欲しい場合でも、名前やIDを使うならfieldsに明示します。

50MBまでの直接アップロードと20MB以上の分割アップロードの使い分け

直接アップロードは1回のリクエストで送る方式で、上限は50MBです。分割アップロードのガイドによると、分割方式は20MB以上のファイルが対象で、セッションを作成し、パートを送り、最後にコミットする流れになります。セッションの有効期間は7日間で、一度送ったパートは上書きできません。

from box_sdk_gen import generate_byte_stream_from_buffer

with open("contract_2026-11.pdf", "rb") as f:
    data = f.read()

client.chunked_uploads.upload_big_file(
    generate_byte_stream_from_buffer(data),
    "contract_2026-11.pdf",
    len(data),
    "123456789",  # 保存先フォルダのID
)

20MB〜50MBは両方式が使える重なりの帯です。実務では、ファイルサイズが20MB以上なら分割方式に切り替える1本の分岐にしておくと、50MBを少し超えた書類で突然失敗する事故を防げます。容量の上限はBoxの契約プランごとに異なり、APIの文書には具体値が載っていないため、自社の契約で確かめます。

メタデータの実装手順：テンプレート付与とSQL風クエリでの検索

テンプレートとインスタンスの関係と二重付与で返る409への対処

メタデータのガイドでは、テンプレートを「ファイルに割り当てて再利用できるキーと値の組の定義」、インスタンスを「テンプレートとファイルの関係と値」と定めています。1つのファイルやフォルダに付けられるテンプレートは100個までです。

付与はメタデータインスタンス作成のリファレンスどおり、POST /2.0/files/{file_id}/metadata/{scope}/{template_key}にJSONを送ります。同じテンプレートが既に付いていると409のtuple_already_exists、型の合わない値は400のschema_validation_failedが返ります。再実行のあるバッチでは、409を受けたら更新処理へ回す分岐を最初から入れておく設計が必要です。

metadata_queries/execute_readで請求書番号から書類を探す

メタデータを付けた書類は、メタデータクエリのリファレンスにあるSQL風の条件で探せます。fromはscope.templateKeyの形式、ancestor_folder_idは必須、1回の上限は100件です。

curl -s -X POST "https://api.box.com/2.0/metadata_queries/execute_read" \
  -H "authorization: Bearer ${ACCESS_TOKEN}" \
  -H "content-type: application/json" \
  -d '{
    "from": "enterprise_123456.invoiceData",
    "query": "invoiceNo = :no",
    "query_params": { "no": "INV-2026-0042" },
    "ancestor_folder_id": "123456789",
    "fields": ["name", "metadata.enterprise_123456.invoiceData.amount"],
    "limit": 100
  }'

既定の応答には項目の最小限の情報しか入らないため、金額などの値が要るときはfieldsにmetadata.<scope>.<templateKey>.<field>の形で指定します。2026年11月時点のリファレンスには、新規の連携ではv2026.0のQuery APIを使うよう注記があります。これから作る連携は、着手時に後継APIの仕様も確認してください。

コラボレーション権限の扱い：7つのロールとウォーターフォール型

POST /2.0/collaborationsで付与できるロールと指定項目

Boxでは、利用者やグループをフォルダやファイルに招待する操作をコラボレーションと呼びます。コラボレーション作成のリファレンスで指定できるロールは、editor、viewer、previewer、uploader、previewer uploader、viewer uploader、co-ownerの7つです。ownerは応答にだけ現れ、リクエストでは指定できません。

curl -s -X POST "https://api.box.com/2.0/collaborations?notify=false" \
  -H "authorization: Bearer ${ACCESS_TOKEN}" \
  -H "content-type: application/json" \
  -d '{
    "item": { "type": "folder", "id": "123456789" },
    "accessible_by": { "type": "group", "id": "987654" },
    "role": "viewer uploader"
  }'

招待先として指定するのは、利用者IDかグループIDです。人の入れ替わりが多い部署は、個人ではなくグループに付与しておくと、異動時にグループのメンバーを変えるだけで済みます。expires_atで期限付きの招待も作れますが、管理コンソールで期限設定が有効になっていないとエラーになります。情報バリアで禁止された組み合わせは403のforbidden_by_policyです。

下位フォルダで権限を絞れないウォーターフォール型の権限設計の落とし穴

Boxの権限の解説によると、招待された人は招待されたフォルダとその配下すべてにアクセスできます。親から引き継いだ権限を配下で変えようとするとエラーになります。

つまり「案件フォルダ全体は閲覧可、その中の見積フォルダだけは見せない」という構成は作れません。見せたくない書類は、別の親フォルダに分けて置くしかありません。逆に、下位で高い権限を与える方法はあり、先に下位フォルダへ高いロールで招待し、その後に親フォルダへ低いロールで招待します。API連携で自動招待を組む場合、招待の順番がそのまま権限の結果を決めるので、処理順をコードに固定しておきます。

本番運用で詰まる上限：毎分1000件の制限と429への備え方

一般API・アップロード・検索それぞれのレート制限の数値と集計単位

公式のレート制限ページの値は次のとおりです。

対象	上限	単位
一般のAPI呼び出し	毎分1000リクエスト	利用者ごと
ファイルのアップロード	毎分240リクエスト	利用者ごと
検索	毎秒6回かつ毎分60回	利用者ごと
検索	毎秒12回	企業全体

見落としやすいのは「利用者ごと」の数え方です。CCGで全処理をサービスアカウント1つにまとめると、全社の連携がその1人分の枠を分け合うことになります。夜間に数万件を移す処理と日中の連携が同じサービスアカウントで動くと、日中の処理まで429で止まります。

retry-afterに従う再試行と契約別の月間コール数上限の確認

上限を超えると429とretry-afterヘッダーが返り、ヘッダーの秒数だけ待ってから再試行します。公式SDKはこの再試行を自動で行いますが、curlや自作のHTTPクライアントでは自分で実装します。待ち時間を延ばしながら再試行する書き方はリトライパターンと指数バックオフの解説、429の設計全般はAPIレート制限の解説にまとめた内容を参照してください。

もう1つの上限が、契約ライセンスに応じた企業単位の月間APIコール数です。毎分の制限に収まっていても、全件同期を毎晩回す設計だと月の枠を使い切る場合があります。大量の同期を組む前に、Boxの契約窓口で自社の月間上限を確かめてください。

Box API連携を自社開発すべき条件と見送るべき場面の判断

自社開発に進むべき条件は業務に合わせたメタデータ連携と権限の自動付与

Box APIを使う開発に投資する価値があるのは、次のどちらかが要件にある場合です。1つは、基幹システムの取引先コードや請求書番号をメタデータとして書類に付け、システム側から書類を引ける状態にしたい場合。もう1つは、人事や案件管理の変更に合わせてフォルダ作成とグループ招待を自動で行い、権限の付け忘れと外し忘れを無くしたい場合です。どちらもiPaaSの定型部品では条件分岐が足りず、409やウォーターフォール型権限の扱いまで組み込むにはコードが要ります。

iPaaSで足りる場面と受託開発へ相談するときの連携要件による判断目安

「添付ファイルをBoxの決まったフォルダに保存する」「新しいファイルが来たらチャットに通知する」程度なら、APIを使う開発は過剰です。iPaaSや各SaaSの標準連携で数日で作れ、保守の手間も小さく済みます。Box製品そのものを使い続けるか迷っている段階なら、先にSharePointとBoxの比較記事で製品選定を済ませるほうが手戻りがありません。

一方、基幹システムとの双方向連携、数万件規模の移行、権限の自動付与のように、認証方式の選定・レート制限の設計・失敗時の再実行まで含めて作る必要がある場合は、設計段階から経験のある開発会社に入ってもらうと安全です。一創のAPI開発・システム連携サービスでは、Boxを含むSaaSと社内システムの連携を、要件整理から運用まで受託しています。汎用的なREST連携の実装手順はAPI連携の実装方法の記事も参考になります。

Box APIの認証・料金・制限について実装前によくある質問

Box APIを使い始める実装者から出やすい質問に、公式ドキュメントの記載をもとに答えます。

Box APIは無料で使えますか？

BoxのアカウントでDeveloper Consoleにアプリを作れば、開発者トークンを使ってすぐに呼び出しを試せます。本番で利用できる範囲は、契約しているBoxのライセンスに応じたものです。公式のレート制限ページには、ライセンスに応じた企業単位の月間APIコール数の上限があると書かれており、アップロードできるファイルサイズの上限もアカウントの種類で変わります。本番で大量の呼び出しを予定するなら、契約窓口で月間上限を確かめてから設計してください。

開発者トークンを本番のバッチで使い続けてもよいですか？

使えません。開発者トークンはDeveloper Consoleにログインしている人に結び付いた普通のアクセストークンで、有効期限は60分です。期限が切れるたびに画面から取り直す必要があり、無人のバッチには向きません。本番ではCCGかJWTでアプリを作り、管理者の承認を受けてから動かします。CCGなら60分ごとにトークンを取り直す処理をSDKが受け持ちます。

CCGとJWTはどちらを選べばよいですか？

両方とも同じサービスアカウントとApp Userを使え、できることに差はありません。違いは認証の仕組みです。CCGはClient IDとClient Secretで認証する方式で、短い実装で済むのが特徴です。JWTはBox側に公開鍵だけを登録し、秘密鍵は自社のサーバーに残ります。シークレットを外部のサービスに預けたくない、鍵の失効と更新を自社で管理したいという方針がある場合はJWT、それ以外はCCGで足ります。

大きなファイルのアップロードが途中で失敗したらどうなりますか？

分割アップロードでは、セッションが7日間有効なので、送り終えたパートを残したまま未送信のパートだけを送り直せます。一度送ったパートは上書きできないため、送信中に元ファイルを書き換えないよう処理を組みます。最後のコミットでファイル全体の整合性が検証され、合わなければ保存されません。50MBを超えるファイルを直接アップロードで送ると失敗するので、20MB以上は分割方式に寄せます。

レート制限に引っかかったときはどう処理すればよいですか？

429が返ったら、retry-afterヘッダーの秒数だけ待って再試行します。公式SDKでは、この再試行は自動です。それでも頻発するなら、処理を用途別のアプリ（それぞれのサービスアカウント）や利用者に分ける、検索を毎秒6回以内に抑える、夜間の大量処理を日中の連携と時間帯で分ける、の順に見直します。制限は利用者ごとに数えられるため、1つのアカウントに全処理を集めない設計が効きます。