プリンシパル & トークン
すべてのAPI認証情報は
cog_ で始まります。すべてのリクエストの Authorization ヘッダーにトークンを含めてください。
- Service User API Key は サービスユーザー として認証されます。つまり、サービスユーザーのID、権限、orgへの所属が適用されます。
- パーソナルアクセストークン は、それを作成した 人間のユーザー として認証されます。つまり、そのユーザーのID、権限、orgへの所属が適用されます。
パーソナルアクセストークンとサービスユーザーの使い分け
目安として、チームを離れたりロールが変わったりしても統合を動作させ続ける必要がある場合は、サービスユーザーを使用します。あなたとまったく同じ権限で実行させる場合は、PATを使用します。
サービスユーザー (自動化に推奨)
サービスユーザーは、API 統合向けに設計された人間以外のアカウントです。RBAC を通じて特定の権限を割り当てることができ、人間のユーザーとは別に組織へ追加できます。仕組み
- 組織の場合は Settings > Devin API (サービスユーザー タブ)、Enterprise の場合は Enterprise settings > Devin API (サービスユーザー タブ) で サービスユーザーをプロビジョニング します
- サービスユーザーがアクセスできるエンドポイントを制御する ロールを割り当て ます
- APIキーをコピー します — キーは
cog_で始まり、プロビジョニング直後に一度だけ表示されます - すべての API リクエストの
Authorizationヘッダーに このキーを含め ます
サービスユーザーのスコープ
create_as_user_id を使ったセッションの帰属
サービスユーザーは、人間のユーザーとは別個の ID です。デフォルトでは、サービスユーザーによって作成されたセッションは、そのサービスユーザー自身に帰属します。特定のユーザー の代わりにセッションを作成する 場合は、セッション作成時に create_as_user_id パラメータを指定します。セッションはそのユーザーのセッション一覧に表示され、そのユーザーの使用量としてカウントされます。
これには、サービスユーザーのロールに ImpersonateOrgSessions 権限が必要です。
キーの主なプロパティ
- キーは
cog_で始まり、作成時に一度だけ表示されます - サービスユーザーは、監査ログ上で人間のユーザーとは別に表示されます
- 権限は RBAC で制御されます — 連携に必要なものだけを付与してください
- Enterprise のサービスユーザーは、すべての組織にわたって org レベルの権限を継承します
パーソナルアクセストークン
パーソナルアクセストークン (PAT) を利用すると、ユーザーは自身の ID でプログラムから認証できます。PAT を利用すると、API からは あなた自身 として認識されます。つまり、あなたの権限、org への所属、監査証跡が適用されます。 これは、共有のサービスユーザー経由ではなく、自分自身として APIコール を行いたい場合 (たとえば、個人用スクリプトやローカルツール) に便利です。 PAT は組織または Enterprise にスコープされません。アカウント内であなたに紐づけられ、アクセス権を持つすべての組織で利用できます。各リクエストでは URL 内で組織を指定し、その組織でのあなたのロールによって、リクエストで実行できる内容が決まります。 Enterprise アカウントでは、PAT は Enterprise 全体のポリシー (デフォルトでは無効) によって管理され、Enterprise 管理者が承認ワークフローやトークンの有効期限の必須化などを設定します。 詳細については、パーソナルアクセストークンを参照してください。レガシー認証 (非推奨)
レガシー API キーは v1 および v2 API で使用されます。非推奨期間中は引き続き利用できますが、RBAC、セッションのアトリビューション、カーソルベースのページネーションといった新機能には対応していません。
発行場所: Settings > API Keys
セキュリティのベストプラクティス
- キーを安全に保管する: 環境変数やシークレット管理システムを使用する
- キーを定期的にローテーションする: 定期的に新しいキーを発行し、古いキーを失効させる
- 自動化にはサービスユーザーを使用する: 本番環境では個人のキーではなくサービスユーザーを優先して使用する
- 最小権限の原則を適用する: 必要最小限の権限のみを付与する
- 利用状況を監視する: 予期しない API の利用がないか監査ログを確認する
- 漏えいしたキーは直ちに失効させる: キーが漏えいした場合は、そのキーを失効させて新しいキーを発行する
トラブルシューティング
401 Unauthorized
考えられる原因:- 無効または期限切れの APIキー
Authorizationヘッダーが設定されていない- Bearer トークン形式の誤り
- Devin MCP でレガシー APIキー (
apk_/apk_user_) を利用している —cog_プレフィックスのキーのみがサポートされています
403 Forbidden
考えられる原因:- API key に必要な権限が付与されていない
- エンドポイントに対して誤ったキー種別を使用している (例: v3 エンドポイントに legacy key を使用している)
- 許可スコープ外のリソースへアクセスしようとしている
- service user に正しいロールと権限が付与されていることを確認する
- legacy v2 エンドポイントの場合: Enterprise Admin ロールを持っていることを確認する
- legacy v1 エンドポイントの場合: 対象の組織 (organization) へのアクセス権があることを確認する
404 Not Found
考えられる原因：- API エンドポイント URL が正しくない
- リソースが存在しない、またはアクセス権限がない
次のステップ
- Teams クイックスタート — 数分で利用開始
- Enterprise クイックスタート — RBAC と複数組織環境のセットアップ
- 一般的なフロー — エンドツーエンドのワークフロー使用例
- 移行ガイド — v1/v2 からの移行