Devin API は、プリンシパル + トークンモデルを利用します。プリンシパルは「誰であるか」 (ID) を表し、トークンはそれをどのように証明するか (認証情報) を表します。この違いを理解することが、ユースケースに適した認証方法を選ぶための鍵となります。
| プリンシパル | トークン | 説明 |
|---|
| サービスユーザー (人間以外) | サービスユーザー APIキー | 自動化された統合および CI/CD パイプライン向け |
| ユーザー (人間) | パーソナルアクセストークン (PAT) | ご自身のユーザーIDで行うプログラムからのアクセス向け |
cog_ で始まります。すべてのリクエストの Authorization ヘッダーにトークンを含めてください。
curl -X GET "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions" \
-H "Authorization: Bearer cog_your_token_here"
- Service User API Key は サービスユーザー として認証されます。つまり、サービスユーザーのアイデンティティ、権限、orgへの所属が適用されます。
- パーソナルアクセストークン は、それを作成した 人間のユーザー として認証されます。つまり、そのユーザーのアイデンティティ、権限、orgへの所属が適用されます。
サービスユーザーは、API 統合向けに設計された人間以外のアカウントです。RBAC を通じて特定の権限を割り当てることができ、人間のユーザーとは別に組織へ追加できます。
- Settings > Service users (組織) または Enterprise settings > Service users (Enterprise) で サービスユーザーを作成 します
- サービスユーザーがアクセスできるエンドポイントを制御する ロールを割り当て ます
- APIキーを生成 します — キーは
cog_ で始まり、作成時に一度だけ表示されます
- すべての API リクエストの
Authorization ヘッダーに このキーを含め ます
curl -X POST "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions" \
-H "Authorization: Bearer $DEVIN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt": "Create a simple Python script"}'
| スコープ | 作成場所 | API アクセス | ユースケース |
|---|
| Organization | Settings > Service users | /v3/organizations/* | セッション管理、Knowledge、プレイブック、シークレット |
| Enterprise | Enterprise settings > Service users | /v3/enterprise/* + /v3/organizations/* | 組織横断の管理、分析、監査ログ、請求 |
Settings > Service Users ページで organization ID を確認してください。
create_as_user_id を使ったセッションの帰属
create_as_user_id パラメータを指定します。セッションはそのユーザーのセッション一覧に表示され、そのユーザーの使用量としてカウントされます。
これには、サービスユーザーのロールに ImpersonateOrgSessions 権限が必要です。
- キーは
cog_ で始まり、作成時に一度だけ表示されます
- サービスユーザーは、監査ログ上で人間のユーザーとは別に表示されます
- 権限は RBAC で制御されます — 連携に必要なものだけを付与してください
- Enterprise のサービスユーザーは、すべての組織にわたって org レベルの権限を継承します
詳細なセットアップ手順については、Teams クイックスタート または Enterprise クイックスタート を参照してください。
パーソナルアクセストークンは現在クローズドベータで、機能フラグで提供されています。アクセスをご希望の場合は、サポートにお問い合わせください。PAT は SSO (シングルサインオン) /Enterprise アカウントでは利用できません。
レガシー API キーは非推奨です。サービスユーザー認証で API v3 を利用してください。移行ガイドを参照してください。 | Key type | Prefix | Used with | Description |
|---|
| Personal API key | apk_user_ | v1, v2 | ユーザーアカウントに紐づき、そのユーザーの権限を継承します |
| Service API key | apk_ | v1 | 組織スコープで、自動化用途向け |
GitHub リポジトリ、クライアントサイドのコード、ログなど、公開されている場所で APIキーを決して共有しないでください。
- キーを安全に保管する: 環境変数やシークレット管理システムを使用する
- キーを定期的にローテーションする: 定期的に新しいキーを発行し、古いキーを失効させる
- 自動化にはサービスユーザーを使用する: 本番環境では個人のキーではなくサービスユーザーを優先して使用する
- 最小権限の原則を適用する: 必要最小限の権限のみを付与する
- 利用状況を監視する: 予期しない API の利用がないか監査ログを確認する
- 漏えいしたキーは直ちに失効させる: キーが漏えいした場合は、そのキーを失効させて新しいキーを発行する
考えられる原因:
- 無効または期限切れの APIキー
Authorization ヘッダーが設定されていない- Bearer トークン形式の誤り
解決策: APIキー が有効であり、Authorization ヘッダーに正しい形式で設定されていることを確認してください。
考えられる原因:
- API key に必要な権限が付与されていない
- エンドポイントに対して誤ったキー種別を使用している (例: v3 エンドポイントに legacy key を使用している)
- 許可スコープ外のリソースへアクセスしようとしている
解決策:
- service user に正しいロールと権限が付与されていることを確認する
- legacy v2 エンドポイントの場合: Enterprise Admin ロールを持っていることを確認する
- legacy v1 エンドポイントの場合: 対象の組織 (organization) へのアクセス権があることを確認する
考えられる原因：
- API エンドポイント URL が正しくない
- リソースが存在しない、またはアクセス権限がない
解決方法： エンドポイント URL とリソースの存在を確認してください。
