Waafir
このページは機械翻訳であり、人による確認を待っています。誤りが含まれている可能性があります。

認証

すべての /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分あたりの上限を宣言しており、エンドポイントに表示されています。それ以外はプラットフォームのデフォルトが適用されます。間隔を空けて再試行してください。

エラーコードのページに、既知のコードとその意味が一覧で記載されています。