Box APIとは？できることや認証方法、Postmanでの使い方を解説

Box APIを利用すると、Box上のファイルやフォルダ、ユーザーなどをプログラムから操作できます。既存の業務システムとBoxを連携したり、ファイル保存やアカウント管理などの定型業務を自動化したりすることも可能です。

一方、Box APIを利用するには、用途に合った認証方法を選び、アプリのスコープやアクセス権限を適切に設定する必要があります。

この記事では、Box APIの概要やできること、外部システムとの連携方法、主な認証方法を解説します。Postmanを使ってBox APIへアクセスし、ルートフォルダ内の項目を取得する手順も紹介します。

Box APIとは

Box APIとは、外部のアプリケーションやシステムから、Box上のデータや機能を利用するためのインターフェースです。

Boxの画面を人が操作する代わりに、プログラムからAPIへリクエストを送ることで、ファイルのアップロードやフォルダの作成、ユーザーの管理などを実行できます。

Box APIは、HTTPを利用してリクエストを送信するREST APIとして提供されています。多くのAPIでは、処理結果やファイル・ユーザーなどの情報をJSON形式で受け取ります。

Box APIへのリクエストには、原則としてアクセストークンが必要です。アクセストークンをリクエストのAuthorizationヘッダーへBearerトークンとして含めることで、Boxはどのユーザーとして実行するリクエストかを識別します。

Box APIを利用すれば、Boxと自社の業務システムを連携したり、Box上で繰り返し行う作業を自動化したりできます。

【関連記事：Boxの使い方をどこよりも詳しく！Boxの基本機能や拡張機能を解説】

Box APIでできること・活用例

Box APIでは、ファイルやフォルダの操作だけでなく、ユーザー管理、共有設定、メタデータの活用など、Boxのさまざまな機能を外部システムから利用できます。

ここでは、Box APIでできる主な操作と、企業における活用例を紹介します。

ファイルやフォルダを操作する

Box APIでは、ファイルやフォルダに対して以下のような操作ができます。

• ファイルのアップロードとダウンロード
• フォルダの作成、移動、コピー、削除
• ファイル名やフォルダ名の変更
• ファイルやフォルダの情報取得
• Box内のコンテンツの検索
• 新しいファイルバージョンのアップロード

例えば、販売管理システムで請求書を発行した際に、取引先ごとのBoxフォルダへ自動的に保存する仕組みを構築できます。担当者が請求書をダウンロードしてBoxへ移す必要がなくなり、保存漏れや保存先の間違いを防ぎやすくなります。

ユーザーやグループを管理する

必要な権限とスコープを設定すれば、Box APIから以下のようなユーザー・グループ管理を行えます。

• 管理対象ユーザーの作成、更新、削除
• グループの作成、更新、削除
• グループへのユーザーの追加
• ユーザーの所属グループの変更
• ユーザー情報やグループ情報の取得

例えば、人事システムへ新入社員が登録されたことをきっかけに、Boxアカウントを作成し、所属部署のグループへ追加する処理を自動化できます。異動時のグループ変更や退職時のアカウント停止なども連携対象にすれば、管理者による手作業を減らせます。

ただし、ユーザーやグループを管理するAPIを利用するには、アプリ側のスコープだけでなく、アクセストークンに関連付けられたユーザーにも管理権限が必要です。

共有やコラボレーションを設定する

Box APIでは、ファイルやフォルダの共有に関する以下の操作も可能です。

• 共有リンクの作成、更新、削除
• フォルダへのコラボレータの追加
• コラボレータに付与する権限の設定
• コラボレーション情報の取得
• コラボレーションの削除

例えば、契約管理システムで契約書の確認が必要になった際に、Box上の契約書へ共有リンクを設定し、担当者へ通知する仕組みを構築できます。

関係者をコラボレータとして自動的に追加し、「閲覧のみ」「編集可能」などの役割を設定することも可能です。ただし、APIから設定できる権限は、アプリのスコープや認証ユーザーが持つ権限の範囲内に限られます。

メタデータやイベントを活用する

Boxでは、ファイルやフォルダへ業務上の情報をメタデータとして付与できます。例えば、契約書に以下のような情報を持たせることが可能です。

• 契約先
• 契約日
• 契約終了日
• 担当部署
• 承認状況

Box APIでは、メタデータの取得・更新や、条件に一致するファイル・フォルダの検索を行えます。フォルダ名や保存場所だけに依存せず、業務上の属性からコンテンツを分類・検索できるようになります。

また、Webhookを利用すると、Box上で発生したイベントを外部システムへ通知できます。ファイルのアップロードや更新を検知し、チャットツールへ通知したり、別システムの処理を開始したりする仕組みを構築できます。

【関連記事：Boxで電子帳簿保存法に対応する具体的な方法を徹底解説】

Boxと外部システムを連携する方法

Boxと外部システムを連携する方法は、Box APIを直接呼び出す方法だけではありません。開発言語や要件、必要なカスタマイズの範囲に応じて、SDKやPostman、iPaaSなども選択できます。

連携方法	主な用途	向いているケース
Box API	HTTPリクエストによる直接連携	独自性の高い処理を実装したい
Box SDK	プログラミング言語を使った開発	APIリクエストや認証処理を効率よく実装したい
Postman	APIの動作確認やテスト	コードを書く前にAPIを試したい
iPaaS・コネクター	画面操作によるサービス連携	開発工数を抑えて連携したい

Box APIを直接利用する

Box APIへHTTPリクエストを直接送る方法は、処理内容を細かく制御しやすい点が特徴です。

既存システムの仕様や自社独自の業務ルールに合わせて、リクエストの送信条件、データの加工方法、エラー時の処理などを設計できます。

一方、認証処理やアクセストークンの更新、エラー処理、レート制限への対応なども自社で実装する必要があります。高度なカスタマイズが必要な場合に適した方法です。

Box SDKを利用する

Boxは、複数のプログラミング言語に対応したSDKを提供しています。

SDKには、Box APIへリクエストを送るためのクラスやメソッドが用意されています。 URLやHTTPヘッダーなどを毎回組み立てる方法と比べて、アプリケーションを実装しやすくなります。

例えば、Python SDKでは、SDKをインストールして認証情報を設定することで、ファイルやフォルダを扱うAPIクライアントを作成できます。

Postmanを利用する

Postmanは、画面上でHTTPリクエストを作成し、APIのレスポンスを確認できるツールです。

プログラムを作成しなくても、リクエスト先のURL、HTTPメソッド、認証情報、パラメータなどを設定してAPIを試せます。そのため、Box APIの仕様確認や、開発前の動作テストに適しています。

Boxは、多数のAPIリクエストがあらかじめ設定されたBox Postmanコレクションを提供しています。リクエストを一から作成しなくても、ファイル、フォルダ、ユーザーなどのリソース別にAPIを試すことが可能です。

iPaaSやコネクターを利用する

iPaaSは、クラウドサービスや業務システムを連携するためのプラットフォームです。 Boxに対応したコネクターがあれば、画面上で処理の流れや条件を設定し、システム間の連携を構築できます。

例えば、特定のシステムにファイルが登録されたらBoxへアップロードする、Boxへファイルが追加されたら別のサービスへ通知するといった連携が考えられます。

ただし、利用できる操作は、iPaaSやコネクターが対応している機能に左右されます。複雑な条件分岐や独自の処理が必要な場合は、Box APIやSDKによる開発のほうが適していることがあります。

Box APIの主な認証方法

Box APIでは、用途やアプリケーションの実行方法に応じて認証方法を選びます。主な認証方法の違いは以下の通りです。

認証方法	ユーザーによる操作	主な用途	管理者の承認・有効化
OAuth 2.0	必要	ユーザー本人の権限で操作するアプリ	企業の設定によって有効化が必要な場合あり
JWT	不要	公開鍵・秘密鍵を使ったサーバ間連携	法人環境では必要
クライアント資格情報許可	不要	クライアントIDとシークレットを使ったサーバ間連携	法人環境では必要

OAuth 2.0はユーザー認証、JWTとクライアント資格情報許可はサーバ認証として利用されます。アクセストークンが表すユーザーは認証方法によって異なり、OAuth 2.0ではアクセスを許可したユーザー、サーバ認証では原則としてアプリケーションのサービスアカウントとなります。

OAuth 2.0

OAuth 2.0は、ユーザーがBoxへログインし、アプリケーションによるアクセスを許可する認証方法です。

発行されたアクセストークンは、アクセスを許可したユーザーに関連付けられます。そのユーザーがアクセスできるファイルやフォルダを、アプリケーションから操作する場合に適しています。

ユーザー自身のBoxアカウントに保存されたデータを扱うWebアプリや、ユーザーごとにBoxとの連携を許可するサービスなどで利用されます。

通常はユーザーが自らアクセスを許可しますが、法人のBox環境で未公開アプリを無効にする設定が有効になっている場合は、管理者によるアプリの有効化が必要になることがあります。

JWT

JWTは、公開鍵と秘密鍵のペアを使ってアプリケーションを認証する方法です。 ユーザーがBoxへログインして許可する操作を必要とせず、バックグラウンドで動作するシステム連携に利用できます。

JWTで認証した場合は、原則としてアプリケーションのサービスアカウントとしてアクセストークンを取得します。設定と権限によっては、企業内の管理対象ユーザーに代わってAPIを実行することも可能です。

法人のBox環境でJWTを使用するアプリは、利用前にBox管理者の承認を受ける必要があります。

クライアント資格情報許可

クライアント資格情報許可は、クライアントIDとクライアントシークレットを使ってアプリケーションを認証する方法です。
JWTと同様に、ユーザーがログインする操作を伴わないサーバ間連携に適しています。公開鍵と秘密鍵の管理を必要とせず、クライアントIDとクライアントシークレットを使ってアクセストークンを取得します。

クライアントシークレットは、アプリケーションの身元を確認するための機密情報です。メール、公開リポジトリ、ブラウザ上で動作するコードなどへ記載せず、安全に管理する必要があります。

Postmanを使ってBox APIを実行する方法

ここからは、OAuth 2.0を使った認証をPostmanで行い、Boxのルートフォルダ内にある項目を取得する手順を解説します。

Boxの画面やPostmanの画面は更新されることがあります。実際に作業する際は、画面上の案内とBox公式のPostmanクイックスタートも確認してください。

BoxアカウントとPostmanを用意する

まず、Box開発者コンソールへログインできるBoxアカウントを用意します。

続いて、Postman公式サイトから、使用しているOSに対応したデスクトップアプリをダウンロードしてインストールします。

PostmanにはWeb版もありますが、デスクトップ版とWeb版ではOAuth 2.0のリダイレクトURIが異なります。ここでは、デスクトップ版を使う場合の手順を紹介します。

Box開発者コンソールでOAuth 2.0アプリを作成する

Box APIへアクセスするには、認証に使用するBoxアプリが必要です。基本的な作成手順は以下の通りです。

• 1.Box開発者コンソールへログインする
• 2.新しいアプリを作成する
• 3.任意のアプリ名を入力する
• 4.アプリの種類または認証方法としてOAuth 2.0を選択する
• 5.アプリを作成する

既存のアプリを使用する場合は、認証方法がOAuth 2.0に設定されていることを確認します。

リダイレクトURIとスコープを設定する

作成したアプリの「構成」画面を開き、OAuth 2.0のリダイレクトURIへ以下を設定します。

https://oauth.pstmn.io/v1/callback

PostmanのWeb版を使用する場合は、以下のリダイレクトURIを使用します。

https://oauth.pstmn.io/v1/browser-callback

続いて、アプリケーションスコープを設定します。ルートフォルダ内の項目を取得するだけであれば、少なくともファイルとフォルダを読み取るスコープが必要です。

ファイルのアップロードやフォルダの作成も試す場合は、ファイルとフォルダの読み書きを許可するスコープを選択します。

設定を保存したら、「OAuth 2.0資格情報」に表示されるクライアントIDとクライアントシークレットを確認します。後の手順で使用するため、安全な場所に控えておきましょう。

法人のBox環境では、管理者の設定によってOAuth 2.0アプリの有効化を求められる場合があります。アプリを利用できない場合は、Box管理者へクライアントIDを伝えて確認してください。

Box Postmanコレクションを追加する

Box公式のPostmanコレクションを開き、自分のPostmanワークスペースへフォークします。

フォークとは、元のコレクションとのつながりを維持したまま、自分のワークスペースへ複製する方法です 。Box公式は、更新を受け取れるように、単純なコピーではなくフォークを推奨しています。

追加が完了すると、PostmanのサイドバーにBox Postmanコレクションが表示されます。コレクション内には、ファイル、フォルダ、ユーザーなど、リソース別に多数のAPIリクエストが用意されています。

Box環境へ認証情報を設定する

Box Postmanコレクションとともに追加された「Box」環境を開き、以下の環境変数を設定します。

変数	設定する値
client_id	BoxアプリのクライアントID
client_secret	Boxアプリのクライアントシークレット
grant_type	authorization_code

入力後、設定内容を保存します。

クライアントシークレットは機密情報です。共有ワークスペースを使用する場合は、他の利用者に値が公開されない設定になっているか確認してください。

認可コードとアクセストークンを取得する

OAuth 2.0の認可コードを取得するため、以下のURLにある[CLIENT_ID]を自分のクライアントIDへ置き換え、Webブラウザで開きます。

https://account.box.com/api/oauth2/authorize?response_type=code&client_id=[CLIENT_ID]&redirect_uri=https://oauth.pstmn.io/v1/callback

Boxへログインし、アプリからのアクセスを許可すると、PostmanのリダイレクトURIへ移動します。

移動後のURLに含まれるcodeパラメータの値をコピーし、PostmanのBox環境にあるcodeへ入力します。認可コードは30秒で期限切れになるため、取得後すぐに次の操作へ進みましょう。

Box Postmanコレクション内の「Authorization」フォルダを開き、「Refresh access token」を選択して「Send」を実行します。認証に成功すると、アクセストークンとリフレッシュトークンが返されます。

取得した値をBox環境の access_tokenとrefresh_token へ設定します。

ルートフォルダ内の項目を取得する

アクセストークンを設定したら、以下の手順でAPIの動作を確認します。

1. Box Postmanコレクション内の「Folders」を開く
2. 「List items in folder」を選択する
3. folder_idが0になっていることを確認する
4. 「Send」を選択する
5. レスポンスの「Body」を確認する

Boxでは、フォルダIDの0がユーザーのルートフォルダを表します。

リクエストに成功すると、ルートフォルダ内のファイルやフォルダの情報がレスポンスへ表示されます。認証エラーが表示された場合は、アクセストークンの期限や環境変数の設定を確認してください。

Box APIを利用するときの注意点

Box APIを本番環境で利用する場合は、動作することだけでなく、認証情報の管理、アクセス権限、レート制限、エラーへの対応も設計する必要があります。

アクセストークンには有効期限がある

OAuth 2.0、JWT、クライアント資格情報許可で発行される
アクセストークンは、通常60分で期限切れになります。

OAuth 2.0では、リフレッシュトークンを使用して新しいアクセストークンを取得できます。Box Postmanコレクションには、アクセストークンの期限切れを検知し、自動的に更新する機能も用意されています。

リフレッシュトークンは一度使用すると新しい値に置き換わります。また、 60日間使用されなかった場合は期限切れになる ため、古い値を再利用しないように管理する必要があります。

スコープとユーザー権限の両方が適用される

Box APIで実行できる操作は、アプリに設定したスコープだけでは決まりません。 アクセストークンに関連付けられたユーザー自身にも、対象となるファイルやフォルダを操作する権限が必要です。

例えば、アプリへファイルの読み取りスコープを付与していても、認証ユーザーが対象ファイルへアクセスできなければ、そのファイルを取得できません。

必要以上に広いスコープを設定するのではなく、アプリの用途に必要な範囲だけを許可することが重要です。

【関連記事：ファイルサーバの管理・運用ルールを最適化！Box移行を成功させる設定のコツ】

APIにはレート制限がある

Box APIには、一定時間内に実行できるリクエスト数の制限があります。

一般的なAPIリクエストは、原則として1ユーザー当たり毎分1,000件です。 ただし、ファイルのアップロードや検索などには個別の制限が設定されています。

レート制限を超えると、「429 Too Many Requests」が返されます。レスポンスのretry-afterヘッダーを確認し、指定された時間を空けてから再実行する必要があります。短い間隔で繰り返し再送するのではなく、待機時間を段階的に延ばす処理も検討しましょう。

また、イッツコムが提供するBox法人向けプランには、プランごとに月当たりのAPIコール数も設定されています。継続的に大量のAPIリクエストを送信するシステムでは、想定する処理件数と契約プランの利用枠を事前に確認することが重要です。

クライアントシークレットを安全に管理する

クライアントシークレット、アクセストークン、リフレッシュトークンは、第三者へ公開しないように管理します。

以下の場所へ直接記載することは避けましょう。

• 公開されるソースコード
• GitHubなどの公開リポジトリ
• ブラウザ上で実行されるJavaScript
• チャットやメールの本文
• 誰でも閲覧できる共有ファイル

本番環境では、環境変数やシークレット管理サービスなどを利用し、必要なアプリケーションだけが認証情報へアクセスできるようにします。

認証情報が漏えいした可能性がある場合は、該当するクライアントシークレットやトークンを失効させ、新しい値へ切り替える必要があります。

エラーの内容を確認して処理する

Box APIでは、処理結果がHTTPステータスコードで返されます。主なエラーと確認項目は以下の通りです。

ステータスコード	主な意味	確認項目
400 Bad Request	リクエスト内容に問題がある	必須パラメータや入力形式
401 Unauthorized	認証に失敗している	アクセストークンの設定や有効期限
403 Forbidden	操作する権限がない	スコープ、ユーザー権限、アプリの承認
404 Not Found	対象が見つからない	ファイル・フォルダIDやアクセス権限
429 Too Many Requests	レート制限を超えた	retry-afterヘッダーと再試行間隔
500番台	Box側で問題が発生した	時間を空けた再試行や稼働状況

エラーが発生した際は、 ステータスコードだけでなく、レスポンスに含まれるcode、message、request_idなども記録しておく と、原因を調査しやすくなります。

Boxの導入・活用はイッツコムにご相談ください

Box APIを利用すると、既存システムとの連携や定型業務の自動化が可能になります。ただし、安定した運用を実現するには、APIの実装だけでなく、Boxのフォルダ構成、ユーザーやグループ、アクセス権限なども適切に設計する必要があります。

イッツコムでは、BoxのBusiness、Business Plus、Enterprise、Enterprise Plusを提供しています。 契約前には、1か月の無料トライアルを利用できます。

オプションの導入・運用コンサルティングでは、現状分析やプランの選定、フォルダ・権限の設計、既存ファイルサーバからのデータ移行などを相談できます。導入後も、ユーザーサポートや活用定着の支援を受けられます。

Box APIや外部システムとの連携を検討する場合は、実現したい業務、必要な操作、APIコール数、認証方式などを整理することが重要です。Boxの導入から運用まで含めて自社に合った環境を整えたい場合は、イッツコムへご相談ください。

まとめ

Box APIを利用すると、ファイルやフォルダの操作、ユーザーやグループの管理、共有設定、メタデータの活用などを外部システムから実行できます。定型作業の自動化や、既存の業務システムとの連携にも活用できます。

認証方法には、OAuth 2.0、JWT、クライアント資格情報許可などがあり、ユーザーによる操作の有無やシステムの構成に応じて選択する必要があります。PostmanとBox Postmanコレクションを利用すれば、プログラムを作成する前にBox APIの動作を確認できます。

本番環境で利用する際は、スコープとユーザー権限、アクセストークンの更新、認証情報の保護、レート制限、エラー処理まで含めて設計しましょう。Boxの導入や運用設計について支援が必要な場合は、イッツコムへお問い合わせください。