認証
すべての /v1 リクエストは認証されます。ご自身のシステムからは、Bearerトークンとして送信する 個人アクセストークン(PAT) で認証します。
Authorization: Bearer waafir_pat_…トークンの発行、制限、取り消しは アドオン → 設定 で行います。発行、有効期限(デフォルトは90日、最長365日)、一度限りの表示、取り消しについては、個人アクセストークンのガイドで説明しています。これらのルールはPlatform APIでも同じです。このページでは、トークンを取得した後にそのトークンで何ができるかを説明します。
個人アクセストークンは、発行した人物の組織の中で その人物として 動作します。トークンがすでに組織を特定しているため、URLやリクエスト本文に組織のパラメータはありません。
3つのトークンチェック
トークンで認証されたリクエストは、他のチェックに加えて、次の3つのチェックを通過する必要があります。組織のセキュリティポリシーやエンドポイント自身のチェックによって拒否されることもあります(後述を参照)。3つのうち2つには専用のコードがあります。ロールによる拒否は、他の拒否と共通の FORBIDDEN を返すことがあるため、コードはエンドポイントの要件とあわせて読み取ってください。
| チェック | 確認内容 | 拒否 |
|---|---|---|
| トークンのスコープ | トークンのスコープは、このエンドポイントが行う処理をカバーしているか | PAT_SCOPE_INSUFFICIENT 403 |
| ロール | 呼び出し元は、このエンドポイントが要求するロールを持っているか | FORBIDDEN 403、または PAT_ROLE_CEILING 403 |
| データルーム | データルームに制限されたトークンの場合、このデータルームはそのリストに含まれているか | PAT_DATAROOM_SCOPE 403 |
トークンのスコープ
トークンは1つのスコープを持ちます。権限の小さい順に read、write、admin です。上位のスコープは、それより下位のスコープをすべて含みます。
エンドポイントに必要なスコープは、デフォルトではHTTPメソッドによって決まります。
GET、HEAD、OPTIONSにはreadが必要です。- その他のメソッド(
POST、PATCH、PUT、DELETE)にはwriteが必要です。
一部のエンドポイントは異なるスコープを宣言しています。よくあるのは、クエリを実行するだけの POST で、これには read だけが必要です。エンドポイントリファレンスには各エンドポイントが実際に要求するスコープが示されているため、メソッドから推測するのではなく、そちらで確認してください。
必要なロールとロールの上限
スコープは トークン に何ができるかを示します。エンドポイントの 必要なロール は、人物 が誰でなければならないかを示します。多くの /v1 エンドポイントは、ディールチーム(組織のオーナー、管理者、またはメンバー)を要求します。チームやアクセス権の付与の変更などには、オーナーまたは管理者が必要です。投資家やその他のゲストはディールチームのロールを持たないため、ディールチーム向けのエンドポイントはそれらを拒否します。その他のエンドポイントは、認証レイヤーでロールの制限を宣言せず、代わりにエンドポイント内でアクセスをチェックします。たとえば、ポートフォリオモニタリングのルートは、モニタリングアドオンと呼び出し元のモニタリングへのアクセス権をチェックします。エンドポイントリファレンスには、各エンドポイントのロールの制限が示されています。何も宣言されていない場合でも、エンドポイント自体が拒否する可能性があると考えてください。
トークンは、発行者の 発行時点の ロールも上限として記録します。Waafirが適用するロールは、発行者の現在のロールとその上限のうち低いほうです。後から管理者に昇格したメンバーも、以前に発行したトークンではメンバーとして動作します。新しいロールを使うには、新しいトークンを発行してください。ロールを引き下げられた人物は、トークンに何が記録されていても、直ちにその権限を失います。いずれの不足も、FORBIDDEN または PAT_ROLE_CEILING として 403 で拒否されます。
データルームに制限されたトークン
すべてのデータルーム ではなく、特定のデータルームを選択して発行したトークンは、それらのデータルームにのみアクセスできます。それ以外のデータルームを指定したリクエストは、PAT_DATAROOM_SCOPE で拒否されます。組織全体を対象とする一部のエンドポイントは、その応答がトークンから見えないデータルームにまたがるため、制限付きトークンを同じコードで一律に拒否します。それらには制限のないトークンを使用してください。GET /api/v1/session はどちらの種類も受け付けます。
その他の拒否
401 UNAUTHORIZED:Authorizationヘッダーがない、またはトークンが不明、期限切れ、取り消し済みです。- 他の組織のリソースに対する
404。 他の組織に属するIDは見つからないものとして扱われるため、存在が確認されることはありません。 - 制限付きファイルに対するオーナー/管理者の特例はありません。 アプリでは、組織のオーナーや管理者はすべての制限付きファイルを閲覧できます。トークンではそうはなりません。トークンが制限付きファイルにアクセスできるのは、トークンの所有者がそのファイルを作成したか、そのファイルへの付与を受けている場合だけです。読み取れないファイルを指定したリクエストには、存在しないファイルと同じ応答(
/api/v1/grantsの場合は、ファイルを示す400、または付与に対する404)が、「not found, or not readable by this credential」というメッセージとともに返されるため、応答によってファイルの存在が確認されることはありません。 - 組織のセキュリティポリシー。 組織にIP許可リストがある場合、リスト外からのリクエストには
IP_BLOCKEDが返されます。二要素認証の強制により、MFA_SETUP_REQUIREDまたはMFA_CHALLENGE_REQUIREDが返されることがあります。 429 RATE_LIMITED。 一部のエンドポイントは、ID(アイデンティティ)ごとの1分あたりの上限を宣言しており、エンドポイントに表示されています。それ以外はプラットフォームのデフォルトが適用されます。間隔を空けて再試行してください。
エラーコードのページに、既知のコードとその意味が一覧で記載されています。