概要
パーソナルアクセストークン (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 統合をテストする場合
- 短期間の自動化 — 自分に紐づく単発のスクリプト
PATの作成と管理
任意の組織またはEnterprise設定の Devin API 設定ページにある PATs タブでPATを管理します。どちらの場合も同じトークンが表示されます (スコープと権限を参照) 。- PATを作成 — 名前と有効期限を設定します。トークンは
cog_で始まり、作成時に一度だけ表示されます。 - トークンを使用 — サービスユーザーAPIキーとまったく同じように、
Authorizationヘッダーで使用します。すべてのAPIコールはユーザーアカウントとして認証され、権限、orgへの所属、監査証跡が適用されます。 - PATをローテーション — 名前を変更せずに、既存のトークンの新しいシークレットを生成します。古いシークレットは直ちに使用できなくなります。
- PATを失効する — いつでもトークンを無効化できます。
Enterprise ガバナンス
Enterprise アカウントでは、PAT の利用可否は、Enterprise 内のすべての組織に適用される Enterprise 全体の PAT ポリシー によって管理されます。Enterprise 設定を管理 権限を持つ Enterprise 管理者は、Enterprise の Devin API 設定ページの PAT ポリシー タブからポリシーを設定し、承認リクエストを処理します。ポリシーモード
有効期限ポリシー
Enterprise で PAT が有効になっている場合、すべての PAT に有効期限を設定する必要があります。有効期限はポリシーで定められた最大有効期間 (デフォルトでは 365 日。管理者はこれより短い上限を設定できます) を超えることはできません。非 Enterprise (Teams) アカウントでは、有効期限のない PAT を作成できます。承認ワークフロー
承認が必要 の場合:- メンバーがPATsタブからPATをリクエストします (名前と有効期限) 。
- Enterprise管理者は Approval queue でリクエストを確認し、承認または拒否します。
- 承認後、メンバーはリクエストを完了してトークンを発行します (トークンは一度だけ表示されます) 。
- 保留中のリクエストは、対応されない場合、7日後 に自動的に失効します。
トークンのインベントリと失効
アカウントのAPIキーを管理 権限を持つ Enterprise 管理者は、PAT ポリシー タブの PAT inventory ビューを開いて、次の操作を行えます。- Enterprise 全体の PAT を閲覧する：各トークンの名前、所有者、作成日、有効期限、ステータス (アクティブ、Revoked、Expired) を確認できます。ステータスで絞り込んだり、名前や所有者で検索したりすることもできます。
- アクティブなトークンをその行から 失効する：インベントリでは、トークンを 1 つずつ失効させます。
自動失効
ユーザーがアカウントのメンバーでなくなると、そのユーザーの PAT は自動的に失効します。これには、SCIM によるプロビジョニング解除や IdP グループの変更による削除も含まれます。セキュリティに関する注意事項
- PATはパスワードと同様に厳重に管理してください。アカウントへの完全なアクセス権を与えます
- PATは環境変数またはシークレットマネージャーに保存し、ソースコードには決して保存しないでください
- ユースケースに必要な最短の有効期限を設定してください
- PATが侵害された場合は、直ちに失効させてください
- 共有または本番環境の自動化には、サービスユーザー APIキーを優先してください
次のステップ
- Authentication overview — 認証の全体像を理解する
- Teams quick start — サービスユーザーの利用を始める