Skip to main content
Devin API は、プリンシパル + トークンモデルを利用します。プリンシパルは「誰であるか」 (ID) を表し、トークンはそれをどのように証明するか (認証情報) を表します。この違いを理解することが、ユースケースに適した認証方法を選ぶための鍵となります。

​
プリンシパル & トークン

すべてのAPI認証情報は cog_ で始まります。すべてのリクエストの Authorization ヘッダーにトークンを含めてください。
重要な違いは、トークンがどの主体として認証されるかです。
  • Service User API Key は サービスユーザー として認証されます。つまり、サービスユーザーのアイデンティティ、権限、orgへの所属が適用されます。
  • パーソナルアクセストークン は、それを作成した 人間のユーザー として認証されます。つまり、そのユーザーのアイデンティティ、権限、orgへの所属が適用されます。
サービスユーザーは、API 統合向けに設計された人間以外のアカウントです。RBAC を通じて特定の権限を割り当てることができ、人間のユーザーとは別に組織へ追加できます。

​
仕組み

  1. Settings > Service users (組織) または Enterprise settings > Service users (Enterprise) で サービスユーザーを作成 します
  2. サービスユーザーがアクセスできるエンドポイントを制御する ロールを割り当て ます
  3. APIキーを生成 します — キーは cog_ で始まり、作成時に一度だけ表示されます
  4. すべての API リクエストの Authorization ヘッダーに このキーを含め ます

​
サービスユーザーのスコープ

Settings > Service Users ページで organization ID を確認してください。

​
create_as_user_id を使ったセッションの帰属

サービスユーザーは、人間のユーザーとは別個の ID です。デフォルトでは、サービスユーザーによって作成されたセッションは、そのサービスユーザー自身に帰属します。特定のユーザー の代わりにセッションを作成する 場合は、セッション作成時に create_as_user_id パラメータを指定します。セッションはそのユーザーのセッション一覧に表示され、そのユーザーの使用量としてカウントされます。 これには、サービスユーザーのロールに ImpersonateOrgSessions 権限が必要です。

​
キーの主なプロパティ

  • キーは cog_ で始まり、作成時に一度だけ表示されます
  • サービスユーザーは、監査ログ上で人間のユーザーとは別に表示されます
  • 権限は RBAC で制御されます — 連携に必要なものだけを付与してください
  • Enterprise のサービスユーザーは、すべての組織にわたって org レベルの権限を継承します
詳細なセットアップ手順については、Teams クイックスタート または Enterprise クイックスタート を参照してください。

​
パーソナルアクセストークン

パーソナルアクセストークン (PAT) を利用すると、ユーザーは自身の ID でプログラムから認証できます。PAT を利用すると、API からは あなた自身 として認識されます。つまり、あなたの権限、org への所属、監査証跡が適用されます。 これは、共有のサービスユーザー経由ではなく、自分自身として APIコール を行いたい場合 (たとえば、個人用スクリプトやローカルツール) に便利です。 Enterprise アカウントでは、PAT は Enterprise 全体のポリシー (デフォルトでは無効) によって管理され、Enterprise 管理者が承認ワークフローやトークンの有効期限の必須化などを設定します。 詳細については、パーソナルアクセストークンを参照してください。

​
レガシー認証 (非推奨)

レガシー API キーは非推奨です。サービスユーザー認証で API v3 を利用してください。移行ガイドを参照してください。
レガシー API キーは v1 および v2 API で使用されます。非推奨期間中は引き続き利用できますが、RBAC、セッションのアトリビューション、カーソルベースのページネーションといった新機能には対応していません。 発行場所: Settings > API Keys

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

GitHub リポジトリ、クライアントサイドのコード、ログなど、公開されている場所で APIキーを決して共有しないでください。
  1. キーを安全に保管する: 環境変数やシークレット管理システムを使用する
  2. キーを定期的にローテーションする: 定期的に新しいキーを発行し、古いキーを失効させる
  3. 自動化にはサービスユーザーを使用する: 本番環境では個人のキーではなくサービスユーザーを優先して使用する
  4. 最小権限の原則を適用する: 必要最小限の権限のみを付与する
  5. 利用状況を監視する: 予期しない API の利用がないか監査ログを確認する
  6. 漏えいしたキーは直ちに失効させる: キーが漏えいした場合は、そのキーを失効させて新しいキーを発行する

​
トラブルシューティング

​
401 Unauthorized

考えられる原因:
  • 無効または期限切れの APIキー
  • Authorization ヘッダーが設定されていない
  • Bearer トークン形式の誤り
  • Devin MCP でレガシー APIキー (apk_ / apk_user_) を利用している — cog_ プレフィックスのキーのみがサポートされています
解決策: APIキー が有効であり、Authorization ヘッダーに正しい形式で設定されていることを確認してください。MCP の使用では、サービスユーザー APIキー (レガシーキーではないもの) を利用していることを確認してください。

​
403 Forbidden

考えられる原因:
  • API key に必要な権限が付与されていない
  • エンドポイントに対して誤ったキー種別を使用している (例: v3 エンドポイントに legacy key を使用している)
  • 許可スコープ外のリソースへアクセスしようとしている
解決策:
  • service user に正しいロールと権限が付与されていることを確認する
  • legacy v2 エンドポイントの場合: Enterprise Admin ロールを持っていることを確認する
  • legacy v1 エンドポイントの場合: 対象の組織 (organization) へのアクセス権があることを確認する

​
404 Not Found

考えられる原因：
  • API エンドポイント URL が正しくない
  • リソースが存在しない、またはアクセス権限がない
解決方法： エンドポイント URL とリソースの存在を確認してください。

​
次のステップ