Skip to main content

​
概要

パーソナルアクセストークン (PAT) を利用すると、人間のユーザーは自分自身のIDでプログラムから認証できます。サービスユーザー APIキー (人間ではないサービスユーザーとして認証するもの) とは異なり、PAT は あなた — つまり、そのトークンを作成した人間のユーザー — として認証されます。 すべてのAPI認証情報は、cog_ プレフィックス形式を利用します。どちらのトークンタイプも、Authorization ヘッダーでは同じ方法で利用します。

​
スコープと権限

PAT は、アカウント (Teams アカウントまたは Enterprise) 内であなたに紐づきます。特定の組織には紐づかず、「組織 PAT」や「Enterprise PAT」というものはありません。これは、組織レベルまたは Enterprise レベルで作成されるサービスユーザーとは異なります。 リクエストごとに組織を指定します。組織エンドポイントでは URL パス (/v3/organizations/{org_id}/...) で組織を指定し、リクエストはその組織でのアクセス権とロールに基づいて認可されます。アクセスできない組織へのリクエストは失敗します。 トークンには、あなたのユーザーと同じ権限があります。web app で実行できることはすべて PAT でも実行できますが、それ以上のことはできません。 PAT を作成、ローテーション、または失効するには、表示している組織で Manage API keys、またはアカウントレベルで アカウントのAPIキーを管理 の権限が必要です。この権限はトークンを管理できるユーザーを制御するものであり、トークンで実行できることは変わりません。 Enterprise アカウントには、Enterprise 全体の設定のみを保存する内部組織もあります。これはワークスペースではありません。この組織を対象とする PAT リクエストは 403 で拒否されるため、必ず子組織の ID を使用してください。

​
PATs を利用する場面

PATs は、自分自身としてプログラムから API にアクセスする必要がある場合に適しています。
  • 個人用スクリプトやツール — 共有のサービスユーザーを使わずに、自分のワークフローを自動化する場合
  • ローカル開発 — 自分のアカウントを使って API 統合をテストする場合
  • 短期間の自動化 — 自分に紐づく単発のスクリプト
本番環境の統合、CI/CD パイプライン、共有の自動化には、代わりに サービスユーザー APIキー を利用してください。サービスユーザーを使うと、監査証跡の向上、一元的なキー管理、RBAC の制御が可能になります。どちらを利用すべきかわからない場合は、比較を参照してください。

​
PATの作成と管理

任意の組織またはEnterprise設定の Devin API 設定ページにある PATs タブでPATを管理します。どちらの場合も同じトークンが表示されます (スコープと権限を参照) 。
  1. PATを作成 — 名前と有効期限を設定します。トークンは cog_ で始まり、作成時に一度だけ表示されます。
  2. トークンを使用 — サービスユーザーAPIキーとまったく同じように、Authorization ヘッダーで使用します。すべてのAPIコールはユーザーアカウントとして認証され、権限、orgへの所属、監査証跡が適用されます。
  3. PATをローテーション — 名前を変更せずに、既存のトークンの新しいシークレットを生成します。古いシークレットは直ちに使用できなくなります。
  4. PATを失効する — いつでもトークンを無効化できます。
PATはACPライブWebSocketなどのリアルタイムエンドポイントでも利用できるため、Devin CLIやデスクトップクライアントなどのツールをPATで認証できます。

​
Enterprise ガバナンス

Enterprise アカウントでは、PAT の利用可否は、Enterprise 内のすべての組織に適用される Enterprise 全体の PAT ポリシー によって管理されます。Enterprise 設定を管理 権限を持つ Enterprise 管理者は、Enterprise の Devin API 設定ページの PAT ポリシー タブからポリシーを設定し、承認リクエストを処理します。

​
ポリシーモード

​
有効期限ポリシー

Enterprise で PAT が有効になっている場合、すべての PAT に有効期限を設定する必要があります。有効期限はポリシーで定められた最大有効期間 (デフォルトでは 365 日。管理者はこれより短い上限を設定できます) を超えることはできません。非 Enterprise (Teams) アカウントでは、有効期限のない PAT を作成できます。

​
承認ワークフロー

承認が必要 の場合:
  1. メンバーがPATsタブからPATをリクエストします (名前と有効期限) 。
  2. Enterprise管理者は Approval queue でリクエストを確認し、承認または拒否します。
  3. 承認後、メンバーはリクエストを完了してトークンを発行します (トークンは一度だけ表示されます) 。
  4. 保留中のリクエストは、対応されない場合、7日後 に自動的に失効します。
リクエスト者と管理者には、トークンのライフサイクルの各段階 (リクエスト、承認、拒否、取り消し) でメール通知が送信されます。

​
トークンの一覧と失効

アカウントのAPIキーを管理できるEnterprise 管理者は次の操作を行えます。
  • トークン一覧でEnterprise全体のすべてのPATを閲覧する。現在のポリシーへの準拠状況も確認できます
  • トークンを一括失効する (例：ポリシーを厳格化した後)
ポリシーを厳格化する (またはPATを無効にする) と、影響を受ける保留中のリクエストはキャンセルされ、一覧では準拠しなくなった既存のトークンにフラグが付けられます。

​
自動失効

ユーザーがアカウントのメンバーでなくなると、そのユーザーの PAT は自動的に失効します。これには、SCIM によるプロビジョニング解除や IdP グループの変更による削除も含まれます。

​
セキュリティに関する注意事項

  • PATはパスワードと同様に厳重に管理してください。アカウントへの完全なアクセス権を与えます
  • PATは環境変数またはシークレットマネージャーに保存し、ソースコードには決して保存しないでください
  • ユースケースに必要な最短の有効期限を設定してください
  • PATが侵害された場合は、直ちに失効させてください
  • 共有または本番環境の自動化には、サービスユーザー APIキーを優先してください

​
次のステップ