Personal Access Tokenを使用してFax.Plus APIにきめ細かなアクセス権を設定する

Personal Access Token(PAT)を使用すると、Fax.Plus APIに安全かつきめ細かくアクセスできます。このガイドでは、連携に必要な権限を持つトークンの作成方法と管理方法を説明します。

Personal Access Tokenの作成

アクセストークンの生成

1. Fax.Plusダッシュボード(app.fax.plus)にログインします
2. 設定 > 連携 > Personal Access Tokensの順に移動します
3. 「新しいトークンを生成」をクリックします

トークンの設定

新しいトークンを生成する際は、次の項目を設定する必要があります。

1. トークン名:トークンの用途がわかる、内容を表す名前を付けます
2. 有効期限:任意の有効期限を設定します(推奨:90日)

利用可能なスコープ

トークンのアクセス権限を定義するスコープを、次の中から1つ以上選択します。

一般的なアクセス

• fax:all:read

  - fax関連のすべての操作に対する読み取り専用アクセス

  • fax、ユーザー、メンバー、電話番号の表示
• fax:all:edit

   - fax関連のすべての操作に対するフルアクセス

  • fax、ユーザー、メンバー、Webhook、電話番号の管理

Webhookの管理

• fax:webhook:read- Webhook設定の表示

• fax:webhook:edit- Webhookの完全な管理機能

faxの操作

• fax:fax:read

  - faxを表示するためのアクセス権

  • 送信トレイの一覧、faxファイル、レポートの表示
• fax:fax:edit

  - faxの完全な管理権限 

  • 送信トレイ、ファイル、faxの詳細の管理

ユーザー管理

• fax:use:read

  - 現在のユーザー(PATの所有者)の詳細を表示

• fax:user:edit

   - 現在のユーザーの詳細を更新

ショップ機能

• fax:shop:read

  - fax番号の閲覧と残高の確認

• fax:shop:edit

  - 電話番号の購入

メンバーアクセス

• fax:member:read

  - アカウントとメンバーの詳細を表示

• fax:member:edit

  - メンバー情報の管理

電話番号の管理

• fax:numbers:read

   - fax番号の一覧表示と詳細の表示

• fax:numbers:edit

  - fax番号の完全な管理

セキュリティのベストプラクティス

1. 最小権限の原則
   • 連携に絶対に必要なスコープのみを付与してください
   • 書き込みアクセスが不要な場合は、読み取り専用のスコープを使用してください
2. トークンのローテーション
   • トークンは90日ごとにローテーションしてください
   • トークンのローテーション用にリマインダーを設定してください
   • サービスを中断させないため、古いトークンの有効期限が切れる前に新しいトークンを作成してください
3. トークンの管理
   • トークンは安全に保管し、決して共有しないでください
   • 漏えいした場合は、ただちにトークンを失効させてください
   • トークンは、アプリケーションの設定内に安全に保存してください

実装のヒント

1. スコープの選択

   • 読み取り専用の操作には、 

     *:read

     スコープを使用します

   • 完全な管理には、 

     *:edit

     スコープを使用します

   • 幅広いアクセスが必要な場合は、 

     fax:all:read

     または 

     fax:all:edit

      の使用を検討してください

2. テスト
   • まず最小限のスコープで連携をテストしてください
   • 必要に応じて、スコープを段階的に追加してください
   • アプリケーションでトークンの有効期限が適切に処理されることを確認してください

トラブルシューティング

アクセスに問題が発生した場合:

1. トークンの有効期限が切れていないか確認します
2. 必要なスコープをすべて選択していることを確認します
3. トークンが失効(削除)されていないか確認します
4. API リクエストでトークンを正しく使用していることを確認します

Personal Access Token は現在ユーザーごとに管理されています。各チームメンバーが、設定 > 連携 > Personal Access Tokens で自分のトークンを作成および失効させます。現時点では、アカウントの他のメンバーの PAT を失効または無効化するための、管理者向けのセルフサービス機能はありません。